diff --git a/en/ruby/resources/beta/index.md b/en/ruby/resources/beta/index.md index a9e79e71..914bc2fe 100644 --- a/en/ruby/resources/beta/index.md +++ b/en/ruby/resources/beta/index.md @@ -1,4367 +1,3925 @@ # Beta -# ChatKit +# Responses -## Domain Types +## Create a model response -### ChatKit Workflow +`beta.responses.create(**kwargs) -> BetaResponse` -- `class ChatKitWorkflow` +**post** `/responses?beta=true` - Workflow metadata and state returned for the session. +Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or +[image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) +or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in +[tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) +or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data +as input for the model's response. - - `id: String` +### Parameters - Identifier of the workflow backing the session. +- `background: bool` - - `state_variables: Hash[Symbol, String | bool | Float]` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. +- `context_management: Array[ContextManagement{ type, compact_threshold}]` - - `String = String` + Context management configuration for this request. - - `UnionMember1 = bool` + - `type: String` - - `Float = Float` + The context management entry type. Currently only 'compaction' is supported. - - `tracing: Tracing{ enabled}` + - `compact_threshold: Integer` - Tracing settings applied to the workflow. + Token threshold at which compaction should be triggered for this entry. - - `enabled: bool` +- `conversation: String | BetaResponseConversationParam` - Indicates whether tracing is enabled. + 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. - - `version: String` + - `String = String` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + The unique ID of the conversation. -# Sessions + - `class BetaResponseConversationParam` -## Cancel chat session + The conversation that this response belongs to. -`beta.chatkit.sessions.cancel(session_id) -> ChatSession` + - `id: String` -**post** `/chatkit/sessions/{session_id}/cancel` + The unique ID of the conversation. -Cancel chat session +- `include: Array[BetaResponseIncludable]` -### Parameters + Specify additional output data to include in the model response. Currently supported values are: -- `session_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). -### Returns + - `:"file_search_call.results"` -- `class ChatSession` + - `:"web_search_call.results"` - Represents a ChatKit session and its resolved configuration. + - `:"web_search_call.action.sources"` - - `id: String` + - `:"message.input_image.image_url"` - Identifier for the ChatKit session. + - `:"computer_call_output.output.image_url"` - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `:"code_interpreter_call.outputs"` - Resolved ChatKit feature configuration for the session. + - `:"reasoning.encrypted_content"` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `:"message.output_text.logprobs"` - Automatic thread titling preferences. +- `input: String | BetaResponseInput` - - `enabled: bool` + Text, image, or file inputs to the model, used to generate a response. - Whether automatic thread titling is enabled. + Learn more: - - `file_upload: ChatSessionFileUpload` + - [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) - Upload settings for the session. + - `String = String` - - `enabled: bool` + A text input to the model, equivalent to a text input with the + `user` role. - Indicates if uploads are enabled for the session. + - `BetaResponseInput = Array[BetaResponseInputItem]` - - `max_file_size: Integer` + A list of one or many input items to the model, containing + different content types. - Maximum upload size in megabytes. + - `class BetaEasyInputMessage` - - `max_files: Integer` + 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. - Maximum number of uploads allowed during the session. + - `content: String | BetaResponseInputMessageContentList` - - `history: ChatSessionHistory` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - History retention configuration. + - `String = String` - - `enabled: bool` + A text input to the model. - Indicates if chat history is persisted for the session. + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `recent_threads: Integer` + A list of one or many input items to the model, containing different content + types. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `class BetaResponseInputText` - - `client_secret: String` + A text input to the model. - Ephemeral client secret that authenticates session requests. + - `text: String` - - `expires_at: Integer` + The text input to the model. - Unix timestamp (in seconds) for when the session expires. + - `type: :input_text` - - `max_requests_per_1_minute: Integer` + The type of the input item. Always `input_text`. - Convenience copy of the per-minute request limit. + - `:input_text` - - `object: :"chatkit.session"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - Type discriminator that is always `chatkit.session`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:"chatkit.session"` + - `mode: :explicit` - - `rate_limits: ChatSessionRateLimits` + The breakpoint mode. Always `explicit`. - Resolved rate limit values. + - `:explicit` - - `max_requests_per_1_minute: Integer` + - `class BetaResponseInputImage` - Maximum allowed requests per one-minute window. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `status: ChatSessionStatus` + - `detail: :low | :high | :auto | :original` - Current lifecycle state of the session. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:active` + - `:low` - - `:expired` + - `:high` - - `:cancelled` + - `:auto` - - `user: String` + - `:original` - User identifier associated with the session. + - `type: :input_image` - - `workflow: ChatKitWorkflow` + The type of the input item. Always `input_image`. - Workflow metadata for the session. + - `:input_image` - - `id: String` + - `file_id: String` - Identifier of the workflow backing the session. + The ID of the file to be sent to the model. - - `state_variables: Hash[Symbol, String | bool | Float]` + - `image_url: String` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `String = String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `UnionMember1 = bool` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Float = Float` + - `mode: :explicit` - - `tracing: Tracing{ enabled}` + The breakpoint mode. Always `explicit`. - Tracing settings applied to the workflow. + - `:explicit` - - `enabled: bool` + - `class BetaResponseInputFile` - Indicates whether tracing is enabled. + A file input to the model. - - `version: String` + - `type: :input_file` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + The type of the input item. Always `input_file`. -### Example + - `:input_file` -```ruby -require "openai" + - `detail: :auto | :low | :high` -openai = OpenAI::Client.new(api_key: "My API Key") + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. -chat_session = openai.beta.chatkit.sessions.cancel("cksess_123") + - `:auto` -puts(chat_session) -``` + - `:low` -#### Response + - `:high` -```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" - } -} -``` + - `file_data: String` -### Example + The content of the file to be sent to the model. -```ruby -require "openai" + - `file_id: String` -openai = OpenAI::Client.new + The ID of the file to be sent to the model. -chat_session = openai.beta.chatkit.sessions.cancel("cksess_123") + - `file_url: String` -puts(chat_session) -``` + The URL of the file to be sent to the model. -#### Response + - `filename: String` -```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 -} -``` + The name of the file to be sent to the model. -## Create ChatKit session + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` -`beta.chatkit.sessions.create(**kwargs) -> ChatSession` + Marks the exact end of a reusable 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** `/chatkit/sessions` + - `mode: :explicit` -Create ChatKit session + The breakpoint mode. Always `explicit`. -### Parameters + - `:explicit` -- `user: String` + - `role: :user | :assistant | :system | :developer` - A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. -- `workflow: ChatSessionWorkflowParam` + - `:user` - Workflow that powers the session. + - `:assistant` - - `id: String` + - `:system` - Identifier for the workflow invoked by the session. + - `:developer` - - `state_variables: Hash[Symbol, String | bool | Float]` + - `phase: :commentary | :final_answer` - 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. + 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 = String` + - `:commentary` - - `UnionMember1 = bool` + - `:final_answer` - - `Float = Float` + - `type: :message` - - `tracing: Tracing{ enabled}` + The type of the message input. Always `message`. - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + - `:message` - - `enabled: bool` + - `class Message` - Whether tracing is enabled during the session. Defaults to true. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `version: String` + - `content: BetaResponseInputMessageContentList` - Specific workflow version to run. Defaults to the latest deployed version. + A list of one or many input items to the model, containing different content + types. -- `chatkit_configuration: ChatSessionChatKitConfigurationParam` + - `role: :user | :system | :developer` - Optional overrides for ChatKit runtime configuration features + The role of the message input. One of `user`, `system`, or `developer`. - - `automatic_thread_titling: AutomaticThreadTitling{ enabled}` + - `:user` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + - `:system` - - `enabled: bool` + - `:developer` - Enable automatic thread title generation. Defaults to true. + - `agent: Agent{ agent_name}` - - `file_upload: FileUpload{ enabled, max_file_size, max_files}` + The agent that produced this item. - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `agent_name: String` - - `enabled: bool` + The canonical name of the agent that produced this item. - Enable uploads for this session. Defaults to false. + - `status: :in_progress | :completed | :incomplete` - - `max_file_size: Integer` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `:in_progress` - - `max_files: Integer` + - `:completed` - Maximum number of files that can be uploaded to the session. Defaults to 10. + - `:incomplete` - - `history: History{ enabled, recent_threads}` + - `type: :message` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + The type of the message input. Always set to `message`. - - `enabled: bool` + - `:message` - Enables chat users to access previous ChatKit threads. Defaults to true. + - `class BetaResponseOutputMessage` - - `recent_threads: Integer` + An output message from the model. - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + - `id: String` -- `expires_after: ChatSessionExpiresAfterParam` + The unique ID of the output message. - Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - - `anchor: :created_at` + The content of the output message. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `class BetaResponseOutputText` - - `:created_at` + A text output from the model. - - `seconds: Integer` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - Number of seconds after the anchor when the session expires. + The annotations of the text output. -- `rate_limits: ChatSessionRateLimitsParam` + - `class FileCitation` - Optional override for per-minute request limits. When omitted, defaults to 10. + A citation to a file. - - `max_requests_per_1_minute: Integer` + - `file_id: String` - Maximum number of requests allowed per minute for the session. Defaults to 10. + The ID of the file. -### Returns + - `filename: String` -- `class ChatSession` + The filename of the file cited. - Represents a ChatKit session and its resolved configuration. + - `index: Integer` - - `id: String` + The index of the file in the list of files. - Identifier for the ChatKit session. + - `type: :file_citation` - - `chatkit_configuration: ChatSessionChatKitConfiguration` + The type of the file citation. Always `file_citation`. - Resolved ChatKit feature configuration for the session. + - `:file_citation` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `class URLCitation` - Automatic thread titling preferences. + A citation for a web resource used to generate a model response. - - `enabled: bool` + - `end_index: Integer` - Whether automatic thread titling is enabled. + The index of the last character of the URL citation in the message. - - `file_upload: ChatSessionFileUpload` + - `start_index: Integer` - Upload settings for the session. + The index of the first character of the URL citation in the message. - - `enabled: bool` + - `title: String` - Indicates if uploads are enabled for the session. + The title of the web resource. - - `max_file_size: Integer` + - `type: :url_citation` - Maximum upload size in megabytes. + The type of the URL citation. Always `url_citation`. - - `max_files: Integer` + - `:url_citation` - Maximum number of uploads allowed during the session. + - `url: String` - - `history: ChatSessionHistory` + The URL of the web resource. - History retention configuration. + - `class ContainerFileCitation` - - `enabled: bool` + A citation for a container file used to generate a model response. - Indicates if chat history is persisted for the session. + - `container_id: String` - - `recent_threads: Integer` + The ID of the container file. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `end_index: Integer` - - `client_secret: String` + The index of the last character of the container file citation in the message. - Ephemeral client secret that authenticates session requests. + - `file_id: String` - - `expires_at: Integer` + The ID of the file. - Unix timestamp (in seconds) for when the session expires. + - `filename: String` - - `max_requests_per_1_minute: Integer` + The filename of the container file cited. - Convenience copy of the per-minute request limit. + - `start_index: Integer` - - `object: :"chatkit.session"` + The index of the first character of the container file citation in the message. - Type discriminator that is always `chatkit.session`. + - `type: :container_file_citation` - - `:"chatkit.session"` + The type of the container file citation. Always `container_file_citation`. - - `rate_limits: ChatSessionRateLimits` + - `:container_file_citation` - Resolved rate limit values. + - `class FilePath` - - `max_requests_per_1_minute: Integer` + A path to a file. - Maximum allowed requests per one-minute window. + - `file_id: String` - - `status: ChatSessionStatus` + The ID of the file. - Current lifecycle state of the session. + - `index: Integer` - - `:active` + The index of the file in the list of files. - - `:expired` + - `type: :file_path` - - `:cancelled` + The type of the file path. Always `file_path`. - - `user: String` + - `:file_path` - User identifier associated with the session. + - `text: String` - - `workflow: ChatKitWorkflow` + The text output from the model. - Workflow metadata for the session. + - `type: :output_text` - - `id: String` + The type of the output text. Always `output_text`. - Identifier of the workflow backing the session. + - `:output_text` - - `state_variables: Hash[Symbol, String | bool | Float]` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `token: String` - - `String = String` + - `bytes: Array[Integer]` - - `UnionMember1 = bool` + - `logprob: Float` - - `Float = Float` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `tracing: Tracing{ enabled}` + - `token: String` - Tracing settings applied to the workflow. + - `bytes: Array[Integer]` - - `enabled: bool` + - `logprob: Float` - Indicates whether tracing is enabled. + - `class BetaResponseOutputRefusal` - - `version: String` + A refusal from the model. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `refusal: String` -### Example + The refusal explanation from the model. -```ruby -require "openai" + - `type: :refusal` -openai = OpenAI::Client.new(api_key: "My API Key") + The type of the refusal. Always `refusal`. -chat_session = openai.beta.chatkit.sessions.create(user: "x", workflow: {id: "id"}) + - `:refusal` -puts(chat_session) -``` + - `role: :assistant` -#### Response + The role of the output message. Always `assistant`. -```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" - } -} -``` + - `:assistant` -### Example + - `status: :in_progress | :completed | :incomplete` -```ruby -require "openai" + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. -openai = OpenAI::Client.new + - `:in_progress` -chat_session = openai.beta.chatkit.sessions.create(user: "user", workflow: {id: "id"}) + - `:completed` -puts(chat_session) -``` + - `:incomplete` -#### Response + - `type: :message` -```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 output message. Always `message`. -# Threads + - `:message` -## List ChatKit thread items + - `agent: Agent{ agent_name}` -`beta.chatkit.threads.list_items(thread_id, **kwargs) -> ConversationCursorPage` + The agent that produced this item. -**get** `/chatkit/threads/{thread_id}/items` + - `agent_name: String` -List ChatKit thread items + The canonical name of the agent that produced this item. -### Parameters + - `phase: :commentary | :final_answer` -- `thread_id: String` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. -- `after: String` + - `:commentary` - List items created after this thread item ID. Defaults to null for the first page. + - `:final_answer` -- `before: String` + - `class BetaResponseFileSearchToolCall` - List items created before this thread item ID. Defaults to null for the newest results. + 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. -- `limit: Integer` + - `id: String` - Maximum number of thread items to return. Defaults to 20. + The unique ID of the file search tool call. -- `order: :asc | :desc` + - `queries: Array[String]` - Sort order for results by creation time. Defaults to `desc`. + The queries used to search for files. - - `:asc` + - `status: :in_progress | :searching | :completed | 2 more` - - `:desc` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, -### Returns + - `:in_progress` -- `ChatKitThreadUserMessageItem | ChatKitThreadAssistantMessageItem | ChatKitWidgetItem | 3 more` + - `:searching` - - `class ChatKitThreadUserMessageItem` + - `:completed` - User-authored messages within a thread. + - `:incomplete` - - `id: String` + - `:failed` - Identifier of the thread item. + - `type: :file_search_call` - - `attachments: Array[ChatKitAttachment]` + The type of the file search tool call. Always `file_search_call`. - Attachments associated with the user message. Defaults to an empty list. + - `:file_search_call` - - `id: String` + - `agent: Agent{ agent_name}` - Identifier for the attachment. + The agent that produced this item. - - `mime_type: String` + - `agent_name: String` - MIME type of the attachment. + The canonical name of the agent that produced this item. - - `name: String` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - Original display name for the attachment. + The results of the file search tool call. - - `preview_url: String` + - `attributes: Hash[Symbol, String | Float | bool]` - Preview URL for rendering the attachment inline. + Set of 16 key-value pairs that can be attached to an object. 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: :image | :file` + - `String = String` - Attachment discriminator. + - `Float = Float` - - `:image` + - `UnionMember2 = bool` - - `:file` + - `file_id: String` - - `content: Array[InputText{ text, type} | QuotedText{ text, type}]` + The unique ID of the file. - Ordered content elements supplied by the user. + - `filename: String` - - `class InputText` + The name of the file. - Text block that a user contributed to the thread. + - `score: Float` + + The relevance score of the file - a value between 0 and 1. - `text: String` - Plain-text content supplied by the user. + The text that was retrieved from the file. - - `type: :input_text` + - `class BetaResponseComputerToolCall` - Type discriminator that is always `input_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. - - `:input_text` + - `id: String` - - `class QuotedText` + The unique ID of the computer call. - Quoted snippet that the user referenced in their message. + - `call_id: String` - - `text: String` + An identifier used when responding to the tool call with output. - Quoted text content. + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `type: :quoted_text` + The pending safety checks for the computer call. - Type discriminator that is always `quoted_text`. + - `id: String` - - `:quoted_text` + The ID of the pending safety check. - - `created_at: Integer` + - `code: String` - Unix timestamp (in seconds) for when the item was created. + The type of the pending safety check. - - `inference_options: InferenceOptions{ model, tool_choice}` + - `message: String` - Inference overrides applied to the message. Defaults to null when unset. + Details about the pending safety check. - - `model: String` + - `status: :in_progress | :completed | :incomplete` - Model name that generated the response. Defaults to null when using the session default. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `tool_choice: ToolChoice{ id}` + - `:in_progress` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `:completed` - - `id: String` + - `:incomplete` - Identifier of the requested tool. + - `type: :computer_call` - - `object: :"chatkit.thread_item"` + The type of the computer call. Always `computer_call`. - Type discriminator that is always `chatkit.thread_item`. + - `:computer_call` - - `:"chatkit.thread_item"` + - `action: BetaComputerAction` - - `thread_id: String` + A click action. - Identifier of the parent thread. + - `class Click` - - `type: :"chatkit.user_message"` + A click action. - - `:"chatkit.user_message"` + - `button: :left | :right | :wheel | 2 more` - - `class ChatKitThreadAssistantMessageItem` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Assistant-authored message within a thread. + - `:left` - - `id: String` + - `:right` - Identifier of the thread item. + - `:wheel` - - `content: Array[ChatKitResponseOutputText]` + - `:back` - Ordered assistant response segments. + - `:forward` - - `annotations: Array[File{ source, type} | URL{ source, type}]` + - `type: :click` - Ordered list of annotations attached to the response text. + Specifies the event type. For a click action, this property is always `click`. - - `class File` + - `:click` - Annotation that references an uploaded file. + - `x: Integer` - - `source: Source{ filename, type}` + The x-coordinate where the click occurred. - File attachment referenced by the annotation. + - `y_: Integer` - - `filename: String` + The y-coordinate where the click occurred. - Filename referenced by the annotation. + - `keys: Array[String]` - - `type: :file` + The keys being held while clicking. - Type discriminator that is always `file`. + - `class DoubleClick` - - `:file` + A double click action. - - `type: :file` + - `keys: Array[String]` - Type discriminator that is always `file` for this annotation. + The keys being held while double-clicking. - - `:file` + - `type: :double_click` - - `class URL` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Annotation that references a URL. + - `:double_click` - - `source: Source{ type, url}` + - `x: Integer` - URL referenced by the annotation. + The x-coordinate where the double click occurred. - - `type: :url` + - `y_: Integer` - Type discriminator that is always `url`. + The y-coordinate where the double click occurred. - - `:url` + - `class Drag` - - `url: String` + A drag action. - URL referenced by the annotation. + - `path: Array[Path{ x, y_}]` - - `type: :url` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Type discriminator that is always `url` for this annotation. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `:url` + - `x: Integer` - - `text: String` + The x-coordinate. - Assistant generated text. + - `y_: Integer` - - `type: :output_text` + The y-coordinate. - Type discriminator that is always `output_text`. + - `type: :drag` - - `:output_text` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `created_at: Integer` + - `:drag` - Unix timestamp (in seconds) for when the item was created. + - `keys: Array[String]` - - `object: :"chatkit.thread_item"` + The keys being held while dragging the mouse. - Type discriminator that is always `chatkit.thread_item`. + - `class Keypress` - - `:"chatkit.thread_item"` + A collection of keypresses the model would like to perform. - - `thread_id: String` + - `keys: Array[String]` - Identifier of the parent thread. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `type: :"chatkit.assistant_message"` + - `type: :keypress` - Type discriminator that is always `chatkit.assistant_message`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `:"chatkit.assistant_message"` + - `:keypress` - - `class ChatKitWidgetItem` + - `class Move` - Thread item that renders a widget payload. + A mouse move action. - - `id: String` + - `type: :move` - Identifier of the thread item. + Specifies the event type. For a move action, this property is always set to `move`. - - `created_at: Integer` + - `:move` - Unix timestamp (in seconds) for when the item was created. + - `x: Integer` - - `object: :"chatkit.thread_item"` + The x-coordinate to move to. - Type discriminator that is always `chatkit.thread_item`. + - `y_: Integer` - - `:"chatkit.thread_item"` + The y-coordinate to move to. - - `thread_id: String` + - `keys: Array[String]` - Identifier of the parent thread. + The keys being held while moving the mouse. - - `type: :"chatkit.widget"` + - `class Screenshot` - Type discriminator that is always `chatkit.widget`. + A screenshot action. - - `:"chatkit.widget"` + - `type: :screenshot` - - `widget: String` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Serialized widget payload rendered in the UI. + - `:screenshot` - - `class ChatKitClientToolCall` + - `class Scroll` - Record of a client side tool invocation initiated by the assistant. + A scroll action. - - `id: String` + - `scroll_x: Integer` - Identifier of the thread item. + The horizontal scroll distance. - - `arguments: String` + - `scroll_y: Integer` - JSON-encoded arguments that were sent to the tool. + The vertical scroll distance. - - `call_id: String` + - `type: :scroll` - Identifier for the client tool call. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `created_at: Integer` + - `:scroll` - Unix timestamp (in seconds) for when the item was created. + - `x: Integer` - - `name: String` + The x-coordinate where the scroll occurred. - Tool name that was invoked. + - `y_: Integer` - - `object: :"chatkit.thread_item"` + The y-coordinate where the scroll occurred. - Type discriminator that is always `chatkit.thread_item`. + - `keys: Array[String]` - - `:"chatkit.thread_item"` + The keys being held while scrolling. - - `output: String` + - `class Type` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + An action to type in text. - - `status: :in_progress | :completed` + - `text: String` - Execution status for the tool call. + The text to type. - - `:in_progress` + - `type: :type` - - `:completed` + Specifies the event type. For a type action, this property is always set to `type`. - - `thread_id: String` + - `:type` - Identifier of the parent thread. + - `class Wait` - - `type: :"chatkit.client_tool_call"` + A wait action. - Type discriminator that is always `chatkit.client_tool_call`. + - `type: :wait` - - `:"chatkit.client_tool_call"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class ChatKitTask` + - `:wait` - Task emitted by the workflow to show progress and status updates. + - `actions: BetaComputerActionList` - - `id: String` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Identifier of the thread item. + - `class Click` - - `created_at: Integer` + A click action. - Unix timestamp (in seconds) for when the item was created. + - `class DoubleClick` - - `heading: String` + A double click action. - Optional heading for the task. Defaults to null when not provided. + - `class Drag` - - `object: :"chatkit.thread_item"` + A drag action. - Type discriminator that is always `chatkit.thread_item`. + - `class Keypress` - - `:"chatkit.thread_item"` + A collection of keypresses the model would like to perform. - - `summary: String` + - `class Move` - Optional summary that describes the task. Defaults to null when omitted. + A mouse move action. - - `task_type: :custom | :thought` + - `class Screenshot` - Subtype for the task. + A screenshot action. - - `:custom` + - `class Scroll` - - `:thought` + A scroll action. - - `thread_id: String` + - `class Type` - Identifier of the parent thread. + An action to type in text. - - `type: :"chatkit.task"` + - `class Wait` - Type discriminator that is always `chatkit.task`. + A wait action. - - `:"chatkit.task"` + - `agent: Agent{ agent_name}` - - `class ChatKitTaskGroup` + The agent that produced this item. - Collection of workflow tasks grouped together in the thread. + - `agent_name: String` - - `id: String` + The canonical name of the agent that produced this item. - Identifier of the thread item. + - `class ComputerCallOutput` - - `created_at: Integer` + The output of a computer tool call. - Unix timestamp (in seconds) for when the item was created. + - `call_id: String` - - `object: :"chatkit.thread_item"` + The ID of the computer tool call that produced the output. - Type discriminator that is always `chatkit.thread_item`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `:"chatkit.thread_item"` + A computer screenshot image used with the computer use tool. - - `tasks: Array[Task{ heading, summary, type}]` + - `type: :computer_screenshot` - Tasks included in the group. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `heading: String` + - `:computer_screenshot` - Optional heading for the grouped task. Defaults to null when not provided. + - `file_id: String` - - `summary: String` + The identifier of an uploaded file that contains the screenshot. - Optional summary that describes the grouped task. Defaults to null when omitted. + - `image_url: String` - - `type: :custom | :thought` + The URL of the screenshot image. - Subtype for the grouped task. + - `type: :computer_call_output` - - `:custom` + The type of the computer tool call output. Always `computer_call_output`. - - `:thought` + - `:computer_call_output` - - `thread_id: String` + - `id: String` - Identifier of the parent thread. + The ID of the computer tool call output. - - `type: :"chatkit.task_group"` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - Type discriminator that is always `chatkit.task_group`. + The safety checks reported by the API that have been acknowledged by the developer. - - `:"chatkit.task_group"` + - `id: String` -### Example + The ID of the pending safety check. -```ruby -require "openai" + - `code: String` -openai = OpenAI::Client.new(api_key: "My API Key") + The type of the pending safety check. -page = openai.beta.chatkit.threads.list_items("cthr_123") + - `message: String` -puts(page) -``` + Details about the pending safety check. -#### Response + - `agent: Agent{ agent_name}` -```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 agent that produced this item. -### Example + - `agent_name: String` -```ruby -require "openai" + The canonical name of the agent that produced this item. -openai = OpenAI::Client.new + - `status: :in_progress | :completed | :incomplete` -page = openai.beta.chatkit.threads.list_items("cthr_123") + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. -puts(page) -``` + - `:in_progress` -#### Response + - `:completed` -```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" -} -``` + - `:incomplete` -## Retrieve ChatKit thread + - `class BetaResponseFunctionWebSearch` -`beta.chatkit.threads.retrieve(thread_id) -> ChatKitThread` + 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. -**get** `/chatkit/threads/{thread_id}` + - `id: String` -Retrieve ChatKit thread + The unique ID of the web search tool call. -### Parameters + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). -### Returns + - `class Search` -- `class ChatKitThread` + Action type "search" - Performs a web search query. - Represents a ChatKit thread and its current status. + - `type: :search` - - `id: String` + The action type. - Identifier of the thread. + - `:search` - - `created_at: Integer` + - `queries: Array[String]` - Unix timestamp (in seconds) for when the thread was created. + The search queries. - - `object: :"chatkit.thread"` + - `query: String` - Type discriminator that is always `chatkit.thread`. + The search query. - - `:"chatkit.thread"` + - `sources: Array[Source{ type, url}]` - - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}` + The sources used in the search. - Current status for the thread. Defaults to `active` for newly created threads. + - `type: :url` - - `class Active` + The type of source. Always `url`. - Indicates that a thread is active. + - `:url` - - `type: :active` + - `url: String` - Status discriminator that is always `active`. + The URL of the source. - - `:active` + - `class OpenPage` - - `class Locked` + Action type "open_page" - Opens a specific URL from search results. - Indicates that a thread is locked and cannot accept new input. + - `type: :open_page` - - `reason: String` + The action type. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `:open_page` - - `type: :locked` + - `url: String` - Status discriminator that is always `locked`. + The URL opened by the model. - - `:locked` + - `class FindInPage` - - `class Closed` + Action type "find_in_page": Searches for a pattern within a loaded page. - Indicates that a thread has been closed. + - `pattern: String` - - `reason: String` + The pattern or text to search for within the page. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `type: :find_in_page` - - `type: :closed` + The action type. - Status discriminator that is always `closed`. + - `:find_in_page` - - `:closed` + - `url: String` - - `title: String` + The URL of the page searched for the pattern. - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `status: :in_progress | :searching | :completed | :failed` - - `user: String` + The status of the web search tool call. - Free-form string that identifies your end user who owns the thread. + - `:in_progress` -### Example + - `:searching` -```ruby -require "openai" + - `:completed` -openai = OpenAI::Client.new(api_key: "My API Key") + - `:failed` -chatkit_thread = openai.beta.chatkit.threads.retrieve("cthr_123") + - `type: :web_search_call` -puts(chatkit_thread) -``` + The type of the web search tool call. Always `web_search_call`. -#### Response + - `:web_search_call` -```json -{ - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" -} -``` + - `agent: Agent{ agent_name}` -### Example + The agent that produced this item. -```ruby -require "openai" + - `agent_name: String` -openai = OpenAI::Client.new + The canonical name of the agent that produced this item. -chatkit_thread = openai.beta.chatkit.threads.retrieve("cthr_123") + - `class BetaResponseFunctionToolCall` -puts(chatkit_thread) -``` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. -#### Response + - `arguments: String` -```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 - } -} -``` + A JSON string of the arguments to pass to the function. -## Delete ChatKit thread + - `call_id: String` -`beta.chatkit.threads.delete(thread_id) -> ThreadDeleteResponse` + The unique ID of the function tool call generated by the model. -**delete** `/chatkit/threads/{thread_id}` + - `name: String` -Delete ChatKit thread + The name of the function to run. -### Parameters + - `type: :function_call` -- `thread_id: String` + The type of the function tool call. Always `function_call`. -### Returns + - `:function_call` -- `class ThreadDeleteResponse` + - `id: String` - Confirmation payload returned after deleting a thread. + The unique ID of the function tool call. - - `id: String` + - `agent: Agent{ agent_name}` - Identifier of the deleted thread. + The agent that produced this item. - - `deleted: bool` + - `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_: Direct{ type} | Program{ caller_id, type}` - Type discriminator that is always `chatkit.thread.deleted`. + The execution context that produced this tool call. - - `:"chatkit.thread.deleted"` + - `class Direct` -### Example + - `type: :direct` -```ruby -require "openai" + - `:direct` -openai = OpenAI::Client.new(api_key: "My API Key") + - `class Program` -thread = openai.beta.chatkit.threads.delete("cthr_123") + - `caller_id: String` -puts(thread) -``` + The call ID of the program item that produced this tool call. -#### Response + - `type: :program` -```json -{ - "id": "id", - "deleted": true, - "object": "chatkit.thread.deleted" -} -``` + - `:program` -### Example + - `namespace: String` -```ruby -require "openai" + The namespace of the function to run. -openai = OpenAI::Client.new + - `status: :in_progress | :completed | :incomplete` -thread = openai.beta.chat_kit.threads.delete("cthr_123") + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -puts(thread) -``` + - `:in_progress` -## List ChatKit threads + - `:completed` -`beta.chatkit.threads.list(**kwargs) -> ConversationCursorPage` + - `:incomplete` -**get** `/chatkit/threads` + - `class FunctionCallOutput` -List ChatKit threads + The output of a function tool call. -### Parameters + - `call_id: String` -- `after: 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. + - `output: String | BetaResponseFunctionCallOutputItemList` -- `before: String` + Text, image, or file output of the function tool call. - List items created before this thread item ID. Defaults to null for the newest results. + - `String = String` -- `limit: Integer` + A JSON string of the output of the function tool call. - Maximum number of thread items to return. Defaults to 20. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` -- `order: :asc | :desc` + An array of content outputs (text, image, file) for the function tool call. - Sort order for results by creation time. Defaults to `desc`. + - `class BetaResponseInputTextContent` - - `:asc` + A text input to the model. - - `:desc` + - `text: String` -- `user: String` + The text input to the model. - Filter threads that belong to this user identifier. Defaults to null to return all users. + - `type: :input_text` -### Returns + The type of the input item. Always `input_text`. -- `class ChatKitThread` + - `:input_text` - Represents a ChatKit thread and its current status. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - Identifier of the thread. + - `mode: :explicit` - - `created_at: Integer` + The breakpoint mode. Always `explicit`. - Unix timestamp (in seconds) for when the thread was created. + - `:explicit` - - `object: :"chatkit.thread"` + - `class BetaResponseInputImageContent` - Type discriminator that is always `chatkit.thread`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `:"chatkit.thread"` + - `type: :input_image` - - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}` + The type of the input item. Always `input_image`. - Current status for the thread. Defaults to `active` for newly created threads. + - `:input_image` - - `class Active` + - `detail: :low | :high | :auto | :original` - Indicates that a thread is active. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :active` + - `:low` - Status discriminator that is always `active`. + - `:high` - - `:active` + - `:auto` - - `class Locked` + - `:original` - Indicates that a thread is locked and cannot accept new input. + - `file_id: String` - - `reason: String` + The ID of the file to be sent to the model. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `image_url: String` - - `type: :locked` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Status discriminator that is always `locked`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:locked` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class Closed` + - `mode: :explicit` - Indicates that a thread has been closed. + The breakpoint mode. Always `explicit`. - - `reason: String` + - `:explicit` - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `class BetaResponseInputFileContent` - - `type: :closed` + A file input to the model. - Status discriminator that is always `closed`. + - `type: :input_file` - - `:closed` + The type of the input item. Always `input_file`. - - `title: String` + - `:input_file` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `detail: :auto | :low | :high` - - `user: 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`. - Free-form string that identifies your end user who owns the thread. + - `:auto` -### Example + - `:low` -```ruby -require "openai" + - `:high` -openai = OpenAI::Client.new(api_key: "My API Key") + - `file_data: String` -page = openai.beta.chatkit.threads.list + The base64-encoded data of the file to be sent to the model. -puts(page) -``` + - `file_id: String` -#### Response + The ID of the file to be sent to the model. -```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" -} -``` + - `file_url: String` -### Example + The URL of the file to be sent to the model. -```ruby -require "openai" + - `filename: String` -openai = OpenAI::Client.new + The name of the file to be sent to the model. -page = openai.beta.chatkit.threads.list + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` -puts(page) -``` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -#### Response + - `mode: :explicit` -```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 breakpoint mode. Always `explicit`. -## Domain Types + - `:explicit` -### Chat Session + - `type: :function_call_output` -- `class ChatSession` + The type of the function tool call output. Always `function_call_output`. - Represents a ChatKit session and its resolved configuration. + - `:function_call_output` - `id: String` - Identifier for the ChatKit session. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `agent: Agent{ agent_name}` - Resolved ChatKit feature configuration for the session. + The agent that produced this item. - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `agent_name: String` - Automatic thread titling preferences. + The canonical name of the agent that produced this item. - - `enabled: bool` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Whether automatic thread titling is enabled. + The execution context that produced this tool call. - - `file_upload: ChatSessionFileUpload` + - `class Direct` - Upload settings for the session. + - `type: :direct` - - `enabled: bool` + The caller type. Always `direct`. - Indicates if uploads are enabled for the session. + - `:direct` - - `max_file_size: Integer` + - `class Program` - Maximum upload size in megabytes. + - `caller_id: String` - - `max_files: Integer` + The call ID of the program item that produced this tool call. - Maximum number of uploads allowed during the session. + - `type: :program` - - `history: ChatSessionHistory` + The caller type. Always `program`. - History retention configuration. + - `:program` - - `enabled: bool` + - `status: :in_progress | :completed | :incomplete` - Indicates if chat history is persisted for the session. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `recent_threads: Integer` + - `:in_progress` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `:completed` - - `client_secret: String` + - `:incomplete` - Ephemeral client secret that authenticates session requests. + - `class AgentMessage` - - `expires_at: Integer` + A message routed between agents. - Unix timestamp (in seconds) for when the session expires. + - `author: String` - - `max_requests_per_1_minute: Integer` + The sending agent identity. - Convenience copy of the per-minute request limit. + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `object: :"chatkit.session"` + Plaintext, image, or encrypted content sent between agents. - Type discriminator that is always `chatkit.session`. + - `class BetaResponseInputTextContent` - - `:"chatkit.session"` + A text input to the model. - - `rate_limits: ChatSessionRateLimits` + - `class BetaResponseInputImageContent` - Resolved rate limit values. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `max_requests_per_1_minute: Integer` + - `class EncryptedContent` - Maximum allowed requests per one-minute window. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `status: ChatSessionStatus` + - `encrypted_content: String` - Current lifecycle state of the session. + Opaque encrypted content. - - `:active` + - `type: :encrypted_content` - - `:expired` + The type of the input item. Always `encrypted_content`. - - `:cancelled` + - `:encrypted_content` - - `user: String` + - `recipient: String` - User identifier associated with the session. + The destination agent identity. - - `workflow: ChatKitWorkflow` + - `type: :agent_message` - Workflow metadata for the session. + The item type. Always `agent_message`. - - `id: String` + - `:agent_message` - Identifier of the workflow backing the session. + - `id: String` - - `state_variables: Hash[Symbol, String | bool | Float]` + The unique ID of this agent message item. - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `agent: Agent{ agent_name}` - - `String = String` + The agent that produced this item. - - `UnionMember1 = bool` + - `agent_name: String` - - `Float = Float` + The canonical name of the agent that produced this item. - - `tracing: Tracing{ enabled}` + - `class MultiAgentCall` - Tracing settings applied to the workflow. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `enabled: bool` + The multi-agent action that was executed. - Indicates whether tracing is enabled. + - `:spawn_agent` - - `version: String` + - `:interrupt_agent` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `:list_agents` -### Chat Session Automatic Thread Titling + - `:send_message` -- `class ChatSessionAutomaticThreadTitling` + - `:followup_task` - Automatic thread title preferences for the session. + - `:wait_agent` - - `enabled: bool` + - `arguments: String` - Whether automatic thread titling is enabled. + The action arguments as a JSON string. -### Chat Session ChatKit Configuration + - `call_id: String` -- `class ChatSessionChatKitConfiguration` + The unique ID linking this call to its output. - ChatKit configuration for the session. + - `type: :multi_agent_call` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + The item type. Always `multi_agent_call`. - Automatic thread titling preferences. + - `:multi_agent_call` - - `enabled: bool` + - `id: String` - Whether automatic thread titling is enabled. + The unique ID of this multi-agent call. - - `file_upload: ChatSessionFileUpload` + - `agent: Agent{ agent_name}` - Upload settings for the session. + The agent that produced this item. - - `enabled: bool` + - `agent_name: String` - Indicates if uploads are enabled for the session. + The canonical name of the agent that produced this item. - - `max_file_size: Integer` + - `class MultiAgentCallOutput` - Maximum upload size in megabytes. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `max_files: Integer` + The multi-agent action that produced this result. - Maximum number of uploads allowed during the session. + - `:spawn_agent` - - `history: ChatSessionHistory` + - `:interrupt_agent` - History retention configuration. + - `:list_agents` - - `enabled: bool` + - `:send_message` - Indicates if chat history is persisted for the session. + - `:followup_task` - - `recent_threads: Integer` + - `:wait_agent` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `call_id: String` -### Chat Session ChatKit Configuration Param + The unique ID of the multi-agent call. -- `class ChatSessionChatKitConfigurationParam` + - `output: Array[Output{ text, type, annotations}]` - Optional per-session configuration settings for ChatKit behavior. + Text output returned by the multi-agent action. - - `automatic_thread_titling: AutomaticThreadTitling{ enabled}` + - `text: String` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + The text content. - - `enabled: bool` + - `type: :output_text` - Enable automatic thread title generation. Defaults to true. + The content type. Always `output_text`. - - `file_upload: FileUpload{ enabled, max_file_size, max_files}` + - `:output_text` - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `enabled: bool` + Citations associated with the text content. - Enable uploads for this session. Defaults to false. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `max_file_size: Integer` + - `file_id: String` - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + The ID of the file. - - `max_files: Integer` + - `filename: String` - Maximum number of files that can be uploaded to the session. Defaults to 10. + The filename of the file cited. - - `history: History{ enabled, recent_threads}` + - `index: Integer` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + The index of the file in the list of files. - - `enabled: bool` + - `type: :file_citation` - Enables chat users to access previous ChatKit threads. Defaults to true. + The citation type. Always `file_citation`. - - `recent_threads: Integer` + - `:file_citation` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` -### Chat Session Expires After Param + - `end_index: Integer` -- `class ChatSessionExpiresAfterParam` + The index of the last character of the citation in the message. - Controls when the session expires relative to an anchor timestamp. + - `start_index: Integer` - - `anchor: :created_at` + The index of the first character of the citation in the message. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `title: String` - - `:created_at` + The title of the cited resource. - - `seconds: Integer` + - `type: :url_citation` - Number of seconds after the anchor when the session expires. + The citation type. Always `url_citation`. -### Chat Session File Upload + - `:url_citation` -- `class ChatSessionFileUpload` + - `url: String` - Upload permissions and limits applied to the session. + The URL of the cited resource. - - `enabled: bool` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - Indicates if uploads are enabled for the session. + - `container_id: String` - - `max_file_size: Integer` + The ID of the container. - Maximum upload size in megabytes. + - `end_index: Integer` - - `max_files: Integer` + The index of the last character of the citation in the message. - Maximum number of uploads allowed during the session. + - `file_id: String` -### Chat Session History + The ID of the container file. -- `class ChatSessionHistory` + - `filename: String` - History retention preferences returned for the session. + The filename of the container file cited. - - `enabled: bool` + - `start_index: Integer` - Indicates if chat history is persisted for the session. + The index of the first character of the citation in the message. - - `recent_threads: Integer` + - `type: :container_file_citation` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + The citation type. Always `container_file_citation`. -### Chat Session Rate Limits + - `:container_file_citation` -- `class ChatSessionRateLimits` + - `type: :multi_agent_call_output` - Active per-minute request limit for the session. + The item type. Always `multi_agent_call_output`. - - `max_requests_per_1_minute: Integer` + - `:multi_agent_call_output` - Maximum allowed requests per one-minute window. + - `id: String` -### Chat Session Rate Limits Param + The unique ID of this multi-agent call output. -- `class ChatSessionRateLimitsParam` + - `agent: Agent{ agent_name}` - Controls request rate limits for the session. + The agent that produced this item. - - `max_requests_per_1_minute: Integer` + - `agent_name: String` - Maximum number of requests allowed per minute for the session. Defaults to 10. + The canonical name of the agent that produced this item. -### Chat Session Status + - `class ToolSearchCall` -- `ChatSessionStatus = :active | :expired | :cancelled` + - `arguments: untyped` - - `:active` + The arguments supplied to the tool search call. - - `:expired` + - `type: :tool_search_call` - - `:cancelled` + The item type. Always `tool_search_call`. -### Chat Session Workflow Param + - `:tool_search_call` -- `class ChatSessionWorkflowParam` + - `id: String` - Workflow reference and overrides applied to the chat session. + The unique ID of this tool search call. - - `id: String` + - `agent: Agent{ agent_name}` - Identifier for the workflow invoked by the session. + The agent that produced this item. - - `state_variables: Hash[Symbol, String | bool | Float]` + - `agent_name: String` - 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 canonical name of the agent that produced this item. - - `String = String` + - `call_id: String` - - `UnionMember1 = bool` + The unique ID of the tool search call generated by the model. - - `Float = Float` + - `execution: :server | :client` - - `tracing: Tracing{ enabled}` + Whether tool search was executed by the server or by the client. - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + - `:server` - - `enabled: bool` + - `:client` - Whether tracing is enabled during the session. Defaults to true. + - `status: :in_progress | :completed | :incomplete` - - `version: String` + The status of the tool search call. - Specific workflow version to run. Defaults to the latest deployed version. + - `:in_progress` -### ChatKit Attachment + - `:completed` -- `class ChatKitAttachment` + - `:incomplete` - Attachment metadata included on thread items. + - `class BetaResponseToolSearchOutputItemParam` - - `id: String` + - `tools: Array[BetaTool]` - Identifier for the attachment. + The loaded tool definitions returned by the tool search output. - - `mime_type: String` + - `class BetaFunctionTool` - MIME type of the attachment. + 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` - Original display name for the attachment. + The name of the function to call. - - `preview_url: String` + - `parameters: Hash[Symbol, untyped]` - Preview URL for rendering the attachment inline. + A JSON schema object describing the parameters of the function. - - `type: :image | :file` + - `strict: bool` - Attachment discriminator. + Whether strict parameter validation is enforced for this function tool. - - `:image` + - `type: :function` - - `:file` + The type of the function tool. Always `function`. -### ChatKit Response Output Text + - `:function` -- `class ChatKitResponseOutputText` + - `allowed_callers: Array[:direct | :programmatic]` - Assistant response text accompanied by optional annotations. + The tool invocation context(s). - - `annotations: Array[File{ source, type} | URL{ source, type}]` + - `:direct` - Ordered list of annotations attached to the response text. + - `:programmatic` - - `class File` + - `defer_loading: bool` - Annotation that references an uploaded file. + Whether this function is deferred and loaded via tool search. - - `source: Source{ filename, type}` + - `description: String` - File attachment referenced by the annotation. + A description of the function. Used by the model to determine whether or not to call the function. - - `filename: String` + - `output_schema: Hash[Symbol, untyped]` - Filename referenced by the annotation. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `type: :file` + - `class BetaFileSearchTool` - Type discriminator that is always `file`. + 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` + - `type: :file_search` - - `type: :file` + The type of the file search tool. Always `file_search`. - Type discriminator that is always `file` for this annotation. + - `:file_search` - - `:file` + - `vector_store_ids: Array[String]` - - `class URL` + The IDs of the vector stores to search. - Annotation that references a URL. + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `source: Source{ type, url}` + A filter to apply. - URL referenced by the annotation. + - `class ComparisonFilter` - - `type: :url` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Type discriminator that is always `url`. + - `key: String` - - `:url` + The key to compare against the value. - - `url: String` + - `type: :eq | :ne | :gt | 5 more` - URL referenced by the annotation. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: :url` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Type discriminator that is always `url` for this annotation. + - `:eq` - - `:url` + - `:ne` - - `text: String` + - `:gt` - Assistant generated text. + - `:gte` - - `type: :output_text` + - `:lt` - Type discriminator that is always `output_text`. + - `:lte` - - `:output_text` + - `:in` -### ChatKit Thread + - `:nin` -- `class ChatKitThread` + - `value: String | Float | bool | Array[String | Float]` - Represents a ChatKit thread and its current status. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: String` + - `String = String` - Identifier of the thread. + - `Float = Float` - - `created_at: Integer` + - `UnionMember2 = bool` - Unix timestamp (in seconds) for when the thread was created. + - `UnionMember3 = Array[String | Float]` - - `object: :"chatkit.thread"` + - `String = String` - Type discriminator that is always `chatkit.thread`. + - `Float = Float` - - `:"chatkit.thread"` + - `class CompoundFilter` - - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}` + Combine multiple filters using `and` or `or`. - Current status for the thread. Defaults to `active` for newly created threads. + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `class Active` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Indicates that a thread is active. + - `class ComparisonFilter` - - `type: :active` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Status discriminator that is always `active`. + - `key: String` - - `:active` + The key to compare against the value. - - `class Locked` + - `type: :eq | :ne | :gt | 5 more` - Indicates that a thread is locked and cannot accept new input. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `reason: 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 - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `:eq` - - `type: :locked` + - `:ne` - Status discriminator that is always `locked`. + - `:gt` - - `:locked` + - `:gte` - - `class Closed` + - `:lt` - Indicates that a thread has been closed. + - `:lte` - - `reason: String` + - `:in` - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `:nin` - - `type: :closed` + - `value: String | Float | bool | Array[String | Float]` - Status discriminator that is always `closed`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `:closed` + - `String = String` - - `title: String` + - `Float = Float` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `UnionMember2 = bool` - - `user: String` + - `UnionMember3 = Array[String | Float]` - Free-form string that identifies your end user who owns the thread. + - `String = String` -### ChatKit Thread Assistant Message Item + - `Float = Float` -- `class ChatKitThreadAssistantMessageItem` + - `UnionMember1 = untyped` - Assistant-authored message within a thread. + - `type: :and | :or` - - `id: String` + Type of operation: `and` or `or`. - Identifier of the thread item. + - `:and` - - `content: Array[ChatKitResponseOutputText]` + - `:or` - Ordered assistant response segments. + - `max_num_results: Integer` - - `annotations: Array[File{ source, type} | URL{ source, type}]` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - Ordered list of annotations attached to the response text. + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - - `class File` + Ranking options for search. - Annotation that references an uploaded file. + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `source: Source{ filename, type}` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - File attachment referenced by the annotation. + - `embedding_weight: Float` - - `filename: String` + The weight of the embedding in the reciprocal ranking fusion. - Filename referenced by the annotation. + - `text_weight: Float` - - `type: :file` + The weight of the text in the reciprocal ranking fusion. - Type discriminator that is always `file`. + - `ranker: :auto | :"default-2024-11-15"` - - `:file` + The ranker to use for the file search. - - `type: :file` + - `:auto` - Type discriminator that is always `file` for this annotation. + - `:"default-2024-11-15"` - - `:file` + - `score_threshold: Float` - - `class URL` + 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. - Annotation that references a URL. + - `class BetaComputerTool` - - `source: Source{ type, url}` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - URL referenced by the annotation. + - `type: :computer` - - `type: :url` + The type of the computer tool. Always `computer`. - Type discriminator that is always `url`. + - `:computer` - - `:url` + - `class BetaComputerUsePreviewTool` - - `url: String` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - URL referenced by the annotation. + - `display_height: Integer` - - `type: :url` + The height of the computer display. - Type discriminator that is always `url` for this annotation. + - `display_width: Integer` - - `:url` + The width of the computer display. - - `text: String` + - `environment: :windows | :mac | :linux | 2 more` - Assistant generated text. + The type of computer environment to control. - - `type: :output_text` + - `:windows` - Type discriminator that is always `output_text`. + - `:mac` - - `:output_text` + - `:linux` - - `created_at: Integer` + - `:ubuntu` - Unix timestamp (in seconds) for when the item was created. + - `:browser` - - `object: :"chatkit.thread_item"` + - `type: :computer_use_preview` - Type discriminator that is always `chatkit.thread_item`. + The type of the computer use tool. Always `computer_use_preview`. - - `:"chatkit.thread_item"` + - `:computer_use_preview` - - `thread_id: String` + - `class BetaWebSearchTool` - Identifier of the parent thread. + 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: :"chatkit.assistant_message"` + - `type: :web_search | :web_search_2025_08_26` - Type discriminator that is always `chatkit.assistant_message`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `:"chatkit.assistant_message"` + - `:web_search` -### ChatKit Thread Item List + - `:web_search_2025_08_26` -- `class ChatKitThreadItemList` + - `filters: Filters{ allowed_domains}` - A paginated list of thread items rendered for the ChatKit API. + Filters for the search. - - `data: Array[ChatKitThreadUserMessageItem | ChatKitThreadAssistantMessageItem | ChatKitWidgetItem | 3 more]` + - `allowed_domains: Array[String]` - A list of items + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `class ChatKitThreadUserMessageItem` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - User-authored messages within a thread. + - `search_context_size: :low | :medium | :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. - Identifier of the thread item. + - `:low` - - `attachments: Array[ChatKitAttachment]` + - `:medium` - Attachments associated with the user message. Defaults to an empty list. + - `:high` - - `id: String` + - `user_location: UserLocation{ city, country, region, 2 more}` - Identifier for the attachment. + The approximate location of the user. - - `mime_type: String` + - `city: String` - MIME type of the attachment. + Free text input for the city of the user, e.g. `San Francisco`. - - `name: String` + - `country: String` - Original display name for the attachment. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `preview_url: String` + - `region: String` - Preview URL for rendering the attachment inline. + Free text input for the region of the user, e.g. `California`. - - `type: :image | :file` + - `timezone: String` - Attachment discriminator. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:image` + - `type: :approximate` - - `:file` + The type of location approximation. Always `approximate`. - - `content: Array[InputText{ text, type} | QuotedText{ text, type}]` + - `:approximate` - Ordered content elements supplied by the user. + - `class Mcp` - - `class InputText` + 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). - Text block that a user contributed to the thread. + - `server_label: String` - - `text: String` + A label for this MCP server, used to identify it in tool calls. - Plain-text content supplied by the user. + - `type: :mcp` - - `type: :input_text` + The type of the MCP tool. Always `mcp`. - Type discriminator that is always `input_text`. + - `:mcp` - - `:input_text` + - `allowed_callers: Array[:direct | :programmatic]` - - `class QuotedText` + The tool invocation context(s). - Quoted snippet that the user referenced in their message. + - `:direct` - - `text: String` + - `:programmatic` - Quoted text content. + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `type: :quoted_text` + List of allowed tool names or a filter object. - Type discriminator that is always `quoted_text`. + - `McpAllowedTools = Array[String]` - - `:quoted_text` + A string array of allowed tool names - - `created_at: Integer` + - `class McpToolFilter` - Unix timestamp (in seconds) for when the item was created. + A filter object to specify which tools are allowed. - - `inference_options: InferenceOptions{ model, tool_choice}` + - `read_only: bool` - Inference overrides applied to the message. Defaults to null when unset. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `model: String` + - `tool_names: Array[String]` - Model name that generated the response. Defaults to null when using the session default. + List of allowed tool names. - - `tool_choice: ToolChoice{ id}` + - `authorization: String` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `id: String` + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - Identifier of the requested tool. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `object: :"chatkit.thread_item"` + Currently supported `connector_id` values are: - Type discriminator that is always `chatkit.thread_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` - - `:"chatkit.thread_item"` + - `:connector_dropbox` - - `thread_id: String` + - `:connector_gmail` - Identifier of the parent thread. + - `:connector_googlecalendar` - - `type: :"chatkit.user_message"` + - `:connector_googledrive` - - `:"chatkit.user_message"` + - `:connector_microsoftteams` - - `class ChatKitThreadAssistantMessageItem` + - `:connector_outlookcalendar` - Assistant-authored message within a thread. + - `:connector_outlookemail` - - `id: String` + - `:connector_sharepoint` - Identifier of the thread item. + - `defer_loading: bool` - - `content: Array[ChatKitResponseOutputText]` + Whether this MCP tool is deferred and discovered via tool search. - Ordered assistant response segments. + - `headers: Hash[Symbol, String]` - - `annotations: Array[File{ source, type} | URL{ source, type}]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Ordered list of annotations attached to the response text. + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `class File` + Specify which of the MCP server's tools require approval. - Annotation that references an uploaded file. + - `class McpToolApprovalFilter` - - `source: Source{ filename, 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. - File attachment referenced by the annotation. + - `always: Always{ read_only, tool_names}` - - `filename: String` + A filter object to specify which tools are allowed. - Filename referenced by the annotation. + - `read_only: bool` - - `type: :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 discriminator that is always `file`. + - `tool_names: Array[String]` - - `:file` + List of allowed tool names. - - `type: :file` + - `never: Never{ read_only, tool_names}` - Type discriminator that is always `file` for this annotation. + A filter object to specify which tools are allowed. - - `:file` + - `read_only: bool` - - `class 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. - Annotation that references a URL. + - `tool_names: Array[String]` - - `source: Source{ type, url}` + List of allowed tool names. - URL referenced by the annotation. + - `McpToolApprovalSetting = :always | :never` - - `type: :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. - Type discriminator that is always `url`. + - `:always` - - `:url` + - `:never` - - `url: String` + - `server_description: String` - URL referenced by the annotation. + Optional description of the MCP server, used to provide more context. - - `type: :url` + - `server_url: String` - Type discriminator that is always `url` for this annotation. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:url` + - `tunnel_id: 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. - Assistant generated text. + - `class CodeInterpreter` - - `type: :output_text` + A tool that runs Python code to help generate a response to a prompt. - Type discriminator that is always `output_text`. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `:output_text` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `created_at: Integer` + - `String = String` - Unix timestamp (in seconds) for when the item was created. + The container ID. - - `object: :"chatkit.thread_item"` + - `class CodeInterpreterToolAuto` - Type discriminator that is always `chatkit.thread_item`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `:"chatkit.thread_item"` + - `type: :auto` - - `thread_id: String` + Always `auto`. - Identifier of the parent thread. + - `:auto` - - `type: :"chatkit.assistant_message"` + - `file_ids: Array[String]` - Type discriminator that is always `chatkit.assistant_message`. + An optional list of uploaded files to make available to your code. - - `:"chatkit.assistant_message"` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `class ChatKitWidgetItem` + The memory limit for the code interpreter container. - Thread item that renders a widget payload. + - `:"1g"` - - `id: String` + - `:"4g"` - Identifier of the thread item. + - `:"16g"` - - `created_at: Integer` + - `:"64g"` - Unix timestamp (in seconds) for when the item was created. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `object: :"chatkit.thread_item"` + Network access policy for the container. - Type discriminator that is always `chatkit.thread_item`. + - `class BetaContainerNetworkPolicyDisabled` - - `:"chatkit.thread_item"` + - `type: :disabled` - - `thread_id: String` + Disable outbound network access. Always `disabled`. - Identifier of the parent thread. + - `:disabled` - - `type: :"chatkit.widget"` + - `class BetaContainerNetworkPolicyAllowlist` - Type discriminator that is always `chatkit.widget`. + - `allowed_domains: Array[String]` - - `:"chatkit.widget"` + A list of allowed domains when type is `allowlist`. - - `widget: String` + - `type: :allowlist` - Serialized widget payload rendered in the UI. + Allow outbound network access only to specified domains. Always `allowlist`. - - `class ChatKitClientToolCall` + - `:allowlist` - Record of a client side tool invocation initiated by the assistant. + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `id: String` + Optional domain-scoped secrets for allowlisted domains. - Identifier of the thread item. + - `domain: String` - - `arguments: String` + The domain associated with the secret. - JSON-encoded arguments that were sent to the tool. + - `name: String` - - `call_id: String` + The name of the secret to inject for the domain. - Identifier for the client tool call. + - `value: String` - - `created_at: Integer` + The secret value to inject for the domain. - Unix timestamp (in seconds) for when the item was created. + - `type: :code_interpreter` - - `name: String` + The type of the code interpreter tool. Always `code_interpreter`. - Tool name that was invoked. + - `:code_interpreter` - - `object: :"chatkit.thread_item"` + - `allowed_callers: Array[:direct | :programmatic]` - Type discriminator that is always `chatkit.thread_item`. + The tool invocation context(s). - - `:"chatkit.thread_item"` + - `:direct` - - `output: String` + - `:programmatic` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `class ProgrammaticToolCalling` - - `status: :in_progress | :completed` + - `type: :programmatic_tool_calling` - Execution status for the tool call. + The type of the tool. Always `programmatic_tool_calling`. - - `:in_progress` + - `:programmatic_tool_calling` - - `:completed` + - `class ImageGeneration` - - `thread_id: String` + A tool that generates images using the GPT image models. - Identifier of the parent thread. + - `type: :image_generation` - - `type: :"chatkit.client_tool_call"` + The type of the image generation tool. Always `image_generation`. - Type discriminator that is always `chatkit.client_tool_call`. + - `:image_generation` - - `:"chatkit.client_tool_call"` + - `action: :generate | :edit | :auto` - - `class ChatKitTask` + Whether to generate a new image or edit an existing image. Default: `auto`. - Task emitted by the workflow to show progress and status updates. + - `:generate` - - `id: String` + - `:edit` - Identifier of the thread item. + - `:auto` - - `created_at: Integer` + - `background: :transparent | :opaque | :auto` - Unix timestamp (in seconds) for when the item was created. + 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. - - `heading: 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. - Optional heading for the task. Defaults to null when not provided. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `object: :"chatkit.thread_item"` + - `:transparent` - Type discriminator that is always `chatkit.thread_item`. + - `:opaque` - - `:"chatkit.thread_item"` + - `:auto` - - `summary: String` + - `input_fidelity: :high | :low` - Optional summary that describes the task. Defaults to null when omitted. + 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`. - - `task_type: :custom | :thought` + - `:high` - Subtype for the task. + - `:low` - - `:custom` + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `:thought` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `thread_id: String` + - `file_id: String` - Identifier of the parent thread. + File ID for the mask image. - - `type: :"chatkit.task"` + - `image_url: String` - Type discriminator that is always `chatkit.task`. + Base64-encoded mask image. - - `:"chatkit.task"` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `class ChatKitTaskGroup` + The image generation model to use. Default: `gpt-image-1`. - Collection of workflow tasks grouped together in the thread. + - `String = String` - - `id: String` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - Identifier of the thread item. + The image generation model to use. Default: `gpt-image-1`. - - `created_at: Integer` + - `:"gpt-image-1"` - Unix timestamp (in seconds) for when the item was created. + - `:"gpt-image-1-mini"` - - `object: :"chatkit.thread_item"` + - `:"gpt-image-2"` - Type discriminator that is always `chatkit.thread_item`. + - `:"gpt-image-2-2026-04-21"` - - `:"chatkit.thread_item"` + - `:"gpt-image-1.5"` - - `tasks: Array[Task{ heading, summary, type}]` + - `:"chatgpt-image-latest"` - Tasks included in the group. + - `moderation: :auto | :low` - - `heading: String` + Moderation level for the generated image. Default: `auto`. - Optional heading for the grouped task. Defaults to null when not provided. + - `:auto` - - `summary: String` + - `:low` - Optional summary that describes the grouped task. Defaults to null when omitted. + - `output_compression: Integer` - - `type: :custom | :thought` + Compression level for the output image. Default: 100. - Subtype for the grouped task. + - `output_format: :png | :webp | :jpeg` - - `:custom` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `:thought` + - `:png` - - `thread_id: String` + - `:webp` - Identifier of the parent thread. + - `:jpeg` - - `type: :"chatkit.task_group"` + - `partial_images: Integer` - Type discriminator that is always `chatkit.task_group`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `:"chatkit.task_group"` + - `quality: :low | :medium | :high | :auto` - - `first_id: String` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The ID of the first item in the list. + - `:low` - - `has_more: bool` + - `:medium` - Whether there are more items available. + - `:high` - - `last_id: String` + - `:auto` - The ID of the last item in the list. + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `object: :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`. - The type of object returned, must be `list`. + - `String = String` - - `:list` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` -### ChatKit Thread User 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`. -- `class ChatKitThreadUserMessageItem` + - `:"1024x1024"` - User-authored messages within a thread. + - `:"1024x1536"` - - `id: String` + - `:"1536x1024"` - Identifier of the thread item. + - `:auto` - - `attachments: Array[ChatKitAttachment]` + - `class LocalShell` - Attachments associated with the user message. Defaults to an empty list. + A tool that allows the model to execute shell commands in a local environment. - - `id: String` + - `type: :local_shell` - Identifier for the attachment. + The type of the local shell tool. Always `local_shell`. - - `mime_type: String` + - `:local_shell` - MIME type of the attachment. + - `class BetaFunctionShellTool` - - `name: String` + A tool that allows the model to execute shell commands. - Original display name for the attachment. + - `type: :shell` - - `preview_url: String` + The type of the shell tool. Always `shell`. - Preview URL for rendering the attachment inline. + - `:shell` - - `type: :image | :file` + - `allowed_callers: Array[:direct | :programmatic]` - Attachment discriminator. + The tool invocation context(s). - - `:image` + - `:direct` - - `:file` + - `:programmatic` - - `content: Array[InputText{ text, type} | QuotedText{ text, type}]` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - Ordered content elements supplied by the user. + - `class BetaContainerAuto` - - `class InputText` + - `type: :container_auto` - Text block that a user contributed to the thread. + Automatically creates a container for this request - - `text: String` + - `:container_auto` - Plain-text content supplied by the user. + - `file_ids: Array[String]` - - `type: :input_text` + An optional list of uploaded files to make available to your code. - Type discriminator that is always `input_text`. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:input_text` + The memory limit for the container. - - `class QuotedText` + - `:"1g"` - Quoted snippet that the user referenced in their message. + - `:"4g"` - - `text: String` + - `:"16g"` - Quoted text content. + - `:"64g"` - - `type: :quoted_text` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - Type discriminator that is always `quoted_text`. + Network access policy for the container. - - `:quoted_text` + - `class BetaContainerNetworkPolicyDisabled` - - `created_at: Integer` + - `class BetaContainerNetworkPolicyAllowlist` - Unix timestamp (in seconds) for when the item was created. + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `inference_options: InferenceOptions{ model, tool_choice}` + An optional list of skills referenced by id or inline data. - Inference overrides applied to the message. Defaults to null when unset. + - `class BetaSkillReference` - - `model: String` + - `skill_id: String` - Model name that generated the response. Defaults to null when using the session default. + The ID of the referenced skill. - - `tool_choice: ToolChoice{ id}` + - `type: :skill_reference` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + References a skill created with the /v1/skills endpoint. - - `id: String` + - `:skill_reference` - Identifier of the requested tool. + - `version: String` - - `object: :"chatkit.thread_item"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Type discriminator that is always `chatkit.thread_item`. + - `class BetaInlineSkill` - - `:"chatkit.thread_item"` + - `description: String` - - `thread_id: String` + The description of the skill. - Identifier of the parent thread. + - `name: String` - - `type: :"chatkit.user_message"` + The name of the skill. - - `:"chatkit.user_message"` + - `source: BetaInlineSkillSource` -### ChatKit Widget Item + Inline skill payload -- `class ChatKitWidgetItem` + - `data: String` - Thread item that renders a widget payload. + Base64-encoded skill zip bundle. - - `id: String` + - `media_type: :"application/zip"` - Identifier of the thread item. + The media type of the inline skill payload. Must be `application/zip`. - - `created_at: Integer` + - `:"application/zip"` - Unix timestamp (in seconds) for when the item was created. + - `type: :base64` - - `object: :"chatkit.thread_item"` + The type of the inline skill source. Must be `base64`. - Type discriminator that is always `chatkit.thread_item`. + - `:base64` - - `:"chatkit.thread_item"` + - `type: :inline` - - `thread_id: String` + Defines an inline skill for this request. - Identifier of the parent thread. + - `:inline` - - `type: :"chatkit.widget"` + - `class BetaLocalEnvironment` - Type discriminator that is always `chatkit.widget`. + - `type: :local` - - `:"chatkit.widget"` + Use a local computer environment. - - `widget: String` + - `:local` - Serialized widget payload rendered in the UI. + - `skills: Array[BetaLocalSkill]` -### Thread Delete Response + An optional list of skills. -- `class ThreadDeleteResponse` + - `description: String` - Confirmation payload returned after deleting a thread. + The description of the skill. - - `id: String` + - `name: String` - Identifier of the deleted thread. + The name of the skill. - - `deleted: bool` + - `path: String` - Indicates that the thread has been deleted. + The path to the directory containing the skill. - - `object: :"chatkit.thread.deleted"` + - `class BetaContainerReference` - Type discriminator that is always `chatkit.thread.deleted`. + - `container_id: String` - - `:"chatkit.thread.deleted"` + The ID of the referenced container. -# Assistants + - `type: :container_reference` -## List assistants + References a container created with the /v1/containers endpoint -`beta.assistants.list(**kwargs) -> CursorPage` + - `:container_reference` -**get** `/assistants` + - `class BetaCustomTool` -List assistants + 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 + - `name: String` -- `after: String` + The name of the custom tool, used to identify it in tool calls. - 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. + - `type: :custom` -- `before: String` + The type of the custom tool. Always `custom`. - 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. + - `:custom` -- `limit: Integer` + - `allowed_callers: Array[:direct | :programmatic]` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The tool invocation context(s). -- `order: :asc | :desc` + - `:direct` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `:programmatic` - - `:asc` + - `defer_loading: bool` - - `:desc` + Whether this tool should be deferred and discovered via tool search. -### Returns + - `description: String` -- `class Assistant` + Optional description of the custom tool, used to provide more context. - Represents an `assistant` that can call the model and use tools. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `id: String` + The input format for the custom tool. Default is unconstrained text. - The identifier, which can be referenced in API endpoints. + - `class Text` - - `created_at: Integer` + Unconstrained free-form text. - The Unix timestamp (in seconds) for when the assistant was created. + - `type: :text` - - `description: String` + Unconstrained text format. Always `text`. - The description of the assistant. The maximum length is 512 characters. + - `:text` - - `instructions: String` + - `class Grammar` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + A grammar defined by the user. - - `metadata: Metadata` + - `definition: 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 grammar definition. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `syntax: :lark | :regex` - - `model: String` + The syntax of the grammar definition. One of `lark` or `regex`. - 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. + - `:lark` - - `name: String` + - `:regex` - The name of the assistant. The maximum length is 256 characters. + - `type: :grammar` - - `object: :assistant` + Grammar format. Always `grammar`. - The object type, which is always `assistant`. + - `:grammar` - - `:assistant` + - `class BetaNamespaceTool` - - `tools: Array[untyped]` + Groups function/custom tools under a shared namespace. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `description: String` - - `response_format: AssistantResponseFormatOption` + A description of the namespace shown to the model. - 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`. + - `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 namespace name used in tool calls (for example, `crm`). - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - **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 function/custom tools available inside this namespace. - - `AssistantResponseFormatOption = :auto` + - `class Function` - `auto` is the default value + - `name: String` - - `:auto` + - `type: :function` - - `class ResponseFormatText` + - `:function` - Default response format. Used to generate text responses. + - `allowed_callers: Array[:direct | :programmatic]` - - `type: :text` + The tool invocation context(s). - The type of response format being defined. Always `text`. + - `:direct` - - `:text` + - `:programmatic` - - `class ResponseFormatJSONObject` + - `defer_loading: bool` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Whether this function should be deferred and discovered via tool search. - - `type: :json_object` + - `description: String` - The type of response format being defined. Always `json_object`. + - `output_schema: Hash[Symbol, untyped]` - - `:json_object` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class ResponseFormatJSONSchema` + - `parameters: untyped` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `strict: bool` - - `json_schema: JSONSchema{ name, description, schema, strict}` + 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. - Structured Outputs configuration options, including a JSON Schema. + - `class BetaCustomTool` - - `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 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: :namespace` - - `description: String` + The type of the tool. Always `namespace`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:namespace` - - `schema: Hash[Symbol, untyped]` + - `class BetaToolSearchTool` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Hosted or BYOT tool search configuration for deferred tools. - - `strict: bool` + - `type: :tool_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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the tool. Always `tool_search`. - - `type: :json_schema` + - `:tool_search` - The type of response format being defined. Always `json_schema`. + - `description: String` - - `:json_schema` + Description shown to the model for a client-executed tool search tool. - - `temperature: Float` + - `execution: :server | :client` - 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. + Whether tool search is executed by the server or by the client. - - `tool_resources: ToolResources{ code_interpreter, file_search}` + - `:server` - 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. + - `:client` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `parameters: untyped` - - `file_ids: Array[String]` + Parameter schema for a client-executed tool search tool. - 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. + - `class BetaWebSearchPreviewTool` - - `file_search: FileSearch{ vector_store_ids}` + 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). - - `vector_store_ids: Array[String]` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - 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 type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `top_p: Float` + - `:web_search_preview` - 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. + - `:web_search_preview_2025_03_11` - We generally recommend altering this or temperature but not both. + - `search_content_types: Array[:text | :image]` -### Example + - `:text` -```ruby -require "openai" + - `:image` -openai = OpenAI::Client.new(api_key: "My API Key") + - `search_context_size: :low | :medium | :high` -page = openai.beta.assistants.list + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. -puts(page) -``` + - `:low` -#### Response + - `:medium` -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "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" -} -``` + - `:high` -## Create assistant + - `user_location: UserLocation{ type, city, country, 2 more}` -`beta.assistants.create(**kwargs) -> Assistant` + The user's location. -**post** `/assistants` + - `type: :approximate` -Create assistant + The type of location approximation. Always `approximate`. -### Parameters + - `:approximate` -- `model: String | ChatModel` + - `city: String` - 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. + Free text input for the city of the user, e.g. `San Francisco`. - - `String = String` + - `country: String` - - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + 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: String` - - `:"gpt-5.6-terra"` + Free text input for the region of the user, e.g. `California`. - - `:"gpt-5.6-luna"` + - `timezone: 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"` + - `class BetaApplyPatchTool` - - `:"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: Array[:direct | :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: :tool_search_output` - - `:"gpt-5.1"` + The item type. Always `tool_search_output`. - - `:"gpt-5.1-2025-11-13"` + - `:tool_search_output` - - `:"gpt-5.1-codex"` + - `id: String` - - `:"gpt-5.1-mini"` + The unique ID of this tool search output. - - `:"gpt-5.1-chat-latest"` + - `agent: Agent{ 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"` + - `call_id: String` - - `:"gpt-5-mini-2025-08-07"` + The unique ID of the tool search call generated by the model. - - `:"gpt-5-nano-2025-08-07"` + - `execution: :server | :client` - - `:"gpt-5-chat-latest"` + Whether tool search was executed by the server or by the client. - - `:"gpt-4.1"` + - `:server` - - `:"gpt-4.1-mini"` + - `:client` - - `:"gpt-4.1-nano"` + - `status: :in_progress | :completed | :incomplete` - - `:"gpt-4.1-2025-04-14"` + The status of the tool search output. - - `:"gpt-4.1-mini-2025-04-14"` + - `:in_progress` - - `:"gpt-4.1-nano-2025-04-14"` + - `:completed` - - `:"o4-mini"` + - `:incomplete` - - `:"o4-mini-2025-04-16"` + - `class AdditionalTools` - - `:o3` + - `role: :developer` - - `:"o3-2025-04-16"` + The role that provided the additional tools. Only `developer` is supported. - - `:"o3-mini"` + - `:developer` - - `:"o3-mini-2025-01-31"` + - `tools: Array[BetaTool]` - - `:o1` + A list of additional tools made available at this item. - - `:"o1-2024-12-17"` + - `class BetaFunctionTool` - - `:"o1-preview"` + 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-preview-2024-09-12"` + - `class BetaFileSearchTool` - - `:"o1-mini"` + 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-mini-2024-09-12"` + - `class BetaComputerTool` - - `:"gpt-4o"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:"gpt-4o-2024-11-20"` + - `class BetaComputerUsePreviewTool` - - `:"gpt-4o-2024-08-06"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:"gpt-4o-2024-05-13"` + - `class BetaWebSearchTool` - - `:"gpt-4o-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-audio-preview-2024-10-01"` + - `class Mcp` - - `:"gpt-4o-audio-preview-2024-12-17"` + 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). - - `:"gpt-4o-audio-preview-2025-06-03"` + - `class CodeInterpreter` - - `:"gpt-4o-mini-audio-preview"` + A tool that runs Python code to help generate a response to a prompt. - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `class ProgrammaticToolCalling` - - `:"gpt-4o-search-preview"` + - `class ImageGeneration` - - `:"gpt-4o-mini-search-preview"` + A tool that generates images using the GPT image models. - - `:"gpt-4o-search-preview-2025-03-11"` + - `class LocalShell` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + A tool that allows the model to execute shell commands in a local environment. - - `:"chatgpt-4o-latest"` + - `class BetaFunctionShellTool` - - `:"codex-mini-latest"` + A tool that allows the model to execute shell commands. - - `:"gpt-4o-mini"` + - `class BetaCustomTool` - - `:"gpt-4o-mini-2024-07-18"` + 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) - - `:"gpt-4-turbo"` + - `class BetaNamespaceTool` - - `:"gpt-4-turbo-2024-04-09"` + Groups function/custom tools under a shared namespace. - - `:"gpt-4-0125-preview"` + - `class BetaToolSearchTool` - - `:"gpt-4-turbo-preview"` + Hosted or BYOT tool search configuration for deferred tools. - - `:"gpt-4-1106-preview"` + - `class BetaWebSearchPreviewTool` - - `:"gpt-4-vision-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"` + - `class BetaApplyPatchTool` - - `:"gpt-4-0314"` + Allows the assistant to create, delete, or update files using unified diffs. - - `:"gpt-4-0613"` + - `type: :additional_tools` - - `:"gpt-4-32k"` + The item type. Always `additional_tools`. - - `:"gpt-4-32k-0314"` + - `:additional_tools` - - `:"gpt-4-32k-0613"` + - `id: String` - - `:"gpt-3.5-turbo"` + The unique ID of this additional tools item. - - `:"gpt-3.5-turbo-16k"` + - `agent: Agent{ agent_name}` - - `:"gpt-3.5-turbo-0301"` + The agent that produced this item. - - `:"gpt-3.5-turbo-0613"` + - `agent_name: String` - - `:"gpt-3.5-turbo-1106"` + The canonical name of the agent that produced this item. - - `:"gpt-3.5-turbo-0125"` + - `class BetaResponseReasoningItem` - - `:"gpt-3.5-turbo-16k-0613"` + 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). -- `description: String` + - `id: String` - The description of the assistant. The maximum length is 512 characters. + The unique identifier of the reasoning content. -- `instructions: String` + - `summary: Array[Summary{ text, type}]` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + Reasoning summary content. -- `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` -- `name: String` + The type of the object. Always `summary_text`. - The name of the assistant. The maximum length is 256 characters. + - `:summary_text` -- `reasoning_effort: ReasoningEffort` + - `type: :reasoning` - 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 object. Always `reasoning`. - - `:none` + - `:reasoning` - - `:minimal` + - `agent: Agent{ 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` + - `content: Array[Content{ text, type}]` - - `:max` + Reasoning text content. -- `response_format: AssistantResponseFormatOption` + - `text: 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 reasoning text from 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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: :reasoning_text` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The type of the reasoning text. Always `reasoning_text`. - **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. + - `:reasoning_text` - - `AssistantResponseFormatOption = :auto` + - `encrypted_content: String` - `auto` is the default value + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `:auto` + - `status: :in_progress | :completed | :incomplete` - - `class ResponseFormatText` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Default response format. Used to generate text responses. + - `:in_progress` - - `type: :text` + - `:completed` - The type of response format being defined. Always `text`. + - `:incomplete` - - `:text` + - `class BetaResponseCompactionItemParam` - - `class ResponseFormatJSONObject` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - 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. + - `encrypted_content: String` - - `type: :json_object` + The encrypted content of the compaction summary. - The type of response format being defined. Always `json_object`. + - `type: :compaction` - - `:json_object` + The type of the item. Always `compaction`. - - `class ResponseFormatJSONSchema` + - `:compaction` - 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: JSONSchema{ name, description, schema, strict}` + The ID of the compaction item. - Structured Outputs configuration options, including a JSON Schema. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `agent_name: String` - - `description: String` + The canonical name of the agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `class ImageGenerationCall` - - `schema: Hash[Symbol, untyped]` + An image generation request made 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/). + - `id: String` - - `strict: bool` + The unique ID of the image generation 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). + - `result: String` - - `type: :json_schema` + The generated image encoded in base64. - The type of response format being defined. Always `json_schema`. + - `status: :in_progress | :completed | :generating | :failed` - - `:json_schema` + The status of the image generation call. -- `temperature: Float` + - `:in_progress` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `:completed` -- `tool_resources: ToolResources{ code_interpreter, file_search}` + - `:generating` - 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. + - `:failed` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `type: :image_generation_call` - - `file_ids: Array[String]` + The type of the image generation call. Always `image_generation_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. + - `:image_generation_call` - - `file_search: FileSearch{ vector_store_ids, vector_stores}` + - `agent: Agent{ agent_name}` - - `vector_store_ids: Array[String]` + The agent that produced this item. - 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. + - `agent_name: String` - - `vector_stores: Array[VectorStore{ chunking_strategy, file_ids, metadata}]` + The canonical name of the agent that produced this item. - 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. + - `class BetaResponseCodeInterpreterToolCall` - - `chunking_strategy: Auto{ type} | Static{ static, type}` + A tool call to run code. - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `id: String` - - `class Auto` + The unique ID of the code interpreter tool call. - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `code: String` - - `type: :auto` + The code to run, or null if not available. - Always `auto`. + - `container_id: String` - - `:auto` + The ID of the container used to run the code. - - `class Static` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `static: Static{ chunk_overlap_tokens, max_chunk_size_tokens}` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `chunk_overlap_tokens: Integer` + - `class Logs` - The number of tokens that overlap between chunks. The default value is `400`. + The logs output from the code interpreter. - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `logs: String` - - `max_chunk_size_tokens: Integer` + The logs output from the code interpreter. - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + - `type: :logs` - - `type: :static` + The type of the output. Always `logs`. - Always `static`. + - `:logs` - - `:static` + - `class Image` - - `file_ids: Array[String]` + The image output from the code interpreter. - 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. + - `type: :image` - - `metadata: Metadata` + The type of the output. Always `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. + - `:image` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `url: String` -- `tools: Array[untyped]` + The URL of the image output from the code interpreter. - 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: :in_progress | :completed | :incomplete | 2 more` -- `top_p: Float` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - 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. + - `:in_progress` - We generally recommend altering this or temperature but not both. + - `:completed` -### Returns + - `:incomplete` -- `class Assistant` + - `:interpreting` - Represents an `assistant` that can call the model and use tools. + - `:failed` - - `id: String` + - `type: :code_interpreter_call` - The identifier, which can be referenced in API endpoints. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `created_at: Integer` + - `:code_interpreter_call` - The Unix timestamp (in seconds) for when the assistant was created. + - `agent: Agent{ agent_name}` - - `description: String` + The agent that produced this item. - The description of the assistant. The maximum length is 512 characters. + - `agent_name: String` - - `instructions: String` + The canonical name of the agent that produced this item. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `class LocalShellCall` - - `metadata: Metadata` + A tool call to run a command on the local shell. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `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 local shell call. - - `model: String` + - `action: Action{ command, env, type, 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. + Execute a shell command on the server. - - `name: String` + - `command: Array[String]` - The name of the assistant. The maximum length is 256 characters. + The command to run. - - `object: :assistant` + - `env: Hash[Symbol, String]` - The object type, which is always `assistant`. + Environment variables to set for the command. - - `:assistant` + - `type: :exec` - - `tools: Array[untyped]` + The type of the local shell action. Always `exec`. - 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`. + - `:exec` - - `response_format: AssistantResponseFormatOption` + - `timeout_ms: Integer` - 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`. + Optional timeout in milliseconds for the command. - 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). + - `user: String` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Optional user to run the command as. - **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. + - `working_directory: String` - - `AssistantResponseFormatOption = :auto` + Optional working directory to run the command in. - `auto` is the default value + - `call_id: String` - - `:auto` + The unique ID of the local shell tool call generated by the model. - - `class ResponseFormatText` + - `status: :in_progress | :completed | :incomplete` - Default response format. Used to generate text responses. + The status of the local shell call. - - `type: :text` + - `:in_progress` - The type of response format being defined. Always `text`. + - `:completed` - - `:text` + - `:incomplete` - - `class ResponseFormatJSONObject` + - `type: :local_shell_call` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The type of the local shell call. Always `local_shell_call`. - - `type: :json_object` + - `:local_shell_call` - The type of response format being defined. Always `json_object`. + - `agent: Agent{ agent_name}` - - `:json_object` + The agent that produced this item. - - `class ResponseFormatJSONSchema` + - `agent_name: 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 canonical name of the agent that produced this item. - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `class LocalShellCallOutput` - Structured Outputs configuration options, including a JSON Schema. + The output of a local shell tool call. - - `name: String` + - `id: String` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The unique ID of the local shell tool call generated by the model. - - `description: String` + - `output: String` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A JSON string of the output of the local shell tool call. - - `schema: Hash[Symbol, untyped]` + - `type: :local_shell_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/). + The type of the local shell tool call output. Always `local_shell_call_output`. - - `strict: bool` + - `: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: Agent{ 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. - - `temperature: Float` + - `status: :in_progress | :completed | :incomplete` - 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 status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `tool_resources: ToolResources{ code_interpreter, file_search}` + - `:in_progress` - 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. + - `:completed` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `:incomplete` - - `file_ids: Array[String]` + - `class ShellCall` - 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. + A tool representing a request to execute one or more shell commands. - - `file_search: FileSearch{ vector_store_ids}` + - `action: Action{ commands, max_output_length, timeout_ms}` - - `vector_store_ids: Array[String]` + The shell commands and limits that describe how to run the tool 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. + - `commands: Array[String]` - - `top_p: Float` + Ordered shell commands for the execution environment to run. - 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. + - `max_output_length: Integer` - We generally recommend altering this or temperature but not both. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. -### Example + - `timeout_ms: Integer` -```ruby -require "openai" + Maximum wall-clock time in milliseconds to allow the shell commands to run. -openai = OpenAI::Client.new(api_key: "My API Key") + - `call_id: String` -assistant = openai.beta.assistants.create(model: :"gpt-4o") + The unique ID of the shell tool call generated by the model. -puts(assistant) -``` + - `type: :shell_call` -#### Response + The type of the item. Always `shell_call`. -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `:shell_call` -## Retrieve assistant + - `id: String` -`beta.assistants.retrieve(assistant_id) -> Assistant` + The unique ID of the shell tool call. Populated when this item is returned via API. -**get** `/assistants/{assistant_id}` + - `agent: Agent{ agent_name}` -Retrieve assistant + The agent that produced this item. -### Parameters + - `agent_name: String` -- `assistant_id: String` + The canonical name of the agent that produced this item. -### Returns + - `caller_: Direct{ type} | Program{ caller_id, type}` -- `class Assistant` + The execution context that produced this tool call. - Represents an `assistant` that can call the model and use tools. + - `class Direct` - - `id: String` + - `type: :direct` - The identifier, which can be referenced in API endpoints. + The caller type. Always `direct`. - - `created_at: Integer` + - `:direct` - The Unix timestamp (in seconds) for when the assistant was created. + - `class Program` - - `description: String` + - `caller_id: String` - The description of the assistant. The maximum length is 512 characters. + The call ID of the program item that produced this tool call. - - `instructions: String` + - `type: :program` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The caller type. Always `program`. - - `metadata: Metadata` + - `:program` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `environment: BetaLocalEnvironment | BetaContainerReference` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The environment to execute the shell commands in. - - `model: String` + - `class BetaLocalEnvironment` - 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. + - `class BetaContainerReference` - - `name: String` + - `status: :in_progress | :completed | :incomplete` - The name of the assistant. The maximum length is 256 characters. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `object: :assistant` + - `:in_progress` - The object type, which is always `assistant`. + - `:completed` - - `:assistant` + - `:incomplete` - - `tools: Array[untyped]` + - `class ShellCallOutput` - 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 streamed output items emitted by a shell tool call. - - `response_format: AssistantResponseFormatOption` + - `call_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 shell tool call generated by 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](https://platform.openai.com/docs/guides/structured-outputs). + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Captured chunks of stdout and stderr output, along with their associated outcomes. - **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. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `AssistantResponseFormatOption = :auto` + The exit or timeout outcome associated with this shell call. - `auto` is the default value + - `class Timeout` - - `:auto` + Indicates that the shell call exceeded its configured time limit. - - `class ResponseFormatText` + - `type: :timeout` - Default response format. Used to generate text responses. + The outcome type. Always `timeout`. - - `type: :text` + - `:timeout` - The type of response format being defined. Always `text`. + - `class Exit` - - `:text` + Indicates that the shell commands finished and returned an exit code. - - `class ResponseFormatJSONObject` + - `exit_code: Integer` - 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 exit code returned by the shell process. - - `type: :json_object` + - `type: :exit` - The type of response format being defined. Always `json_object`. + The outcome type. Always `exit`. - - `:json_object` + - `:exit` - - `class ResponseFormatJSONSchema` + - `stderr: String` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Captured stderr output for the shell call. - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `stdout: String` - Structured Outputs configuration options, including a JSON Schema. + Captured stdout output for the shell call. - - `name: String` + - `type: :shell_call_output` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The type of the item. Always `shell_call_output`. - - `description: String` + - `:shell_call_output` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `id: String` - - `schema: Hash[Symbol, untyped]` + The unique ID of the shell tool call output. Populated when this item is returned via API. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `agent: Agent{ agent_name}` - - `strict: bool` + 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). + - `agent_name: String` - - `type: :json_schema` + The canonical name of the agent that produced this item. - The type of response format being defined. Always `json_schema`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:json_schema` + The execution context that produced this tool call. - - `temperature: Float` + - `class Direct` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `type: :direct` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + The caller type. Always `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. + - `:direct` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `class Program` - - `file_ids: Array[String]` + - `caller_id: 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. + The call ID of the program item that produced this tool call. - - `file_search: FileSearch{ vector_store_ids}` + - `type: :program` - - `vector_store_ids: Array[String]` + The caller type. Always `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. + - `:program` - - `top_p: Float` + - `max_output_length: Integer` - 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 maximum number of UTF-8 characters captured for this shell call's combined output. - We generally recommend altering this or temperature but not both. + - `status: :in_progress | :completed | :incomplete` -### Example + The status of the shell call output. -```ruby -require "openai" + - `:in_progress` -openai = OpenAI::Client.new(api_key: "My API Key") + - `:completed` -assistant = openai.beta.assistants.retrieve("assistant_id") + - `:incomplete` -puts(assistant) -``` + - `class ApplyPatchCall` -#### Response + A tool call representing a request to create, delete, or update files using diff patches. -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `call_id: String` -## Modify assistant + The unique ID of the apply patch tool call generated by the model. -`beta.assistants.update(assistant_id, **kwargs) -> Assistant` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` -**post** `/assistants/{assistant_id}` + The specific create, delete, or update instruction for the apply_patch tool call. -Modify assistant + - `class CreateFile` -### Parameters + Instruction for creating a new file via the apply_patch tool. -- `assistant_id: String` + - `diff: String` -- `description: String` + Unified diff content to apply when creating the file. - The description of the assistant. The maximum length is 512 characters. + - `path: String` -- `instructions: String` + Path of the file to create relative to the workspace root. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `type: :create_file` -- `metadata: Metadata` + The operation type. Always `create_file`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:create_file` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class DeleteFile` -- `model: String | :"gpt-5" | :"gpt-5-mini" | :"gpt-5-nano" | 39 more` + Instruction for deleting an existing file via the apply_patch tool. - 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. + - `path: String` - - `String = String` + Path of the file to delete relative to the workspace root. - - `Model = :"gpt-5" | :"gpt-5-mini" | :"gpt-5-nano" | 39 more` + - `type: :delete_file` - 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 operation type. Always `delete_file`. - - `:"gpt-5"` + - `:delete_file` - - `:"gpt-5-mini"` + - `class UpdateFile` - - `:"gpt-5-nano"` + Instruction for updating an existing file via the apply_patch tool. - - `:"gpt-5-2025-08-07"` + - `diff: String` - - `:"gpt-5-mini-2025-08-07"` + Unified diff content to apply to the existing file. - - `:"gpt-5-nano-2025-08-07"` + - `path: String` - - `:"gpt-4.1"` + Path of the file to update relative to the workspace root. - - `:"gpt-4.1-mini"` + - `type: :update_file` - - `:"gpt-4.1-nano"` + The operation type. Always `update_file`. - - `:"gpt-4.1-2025-04-14"` + - `:update_file` - - `:"gpt-4.1-mini-2025-04-14"` + - `status: :in_progress | :completed` - - `:"gpt-4.1-nano-2025-04-14"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:"o3-mini"` + - `:in_progress` - - `:"o3-mini-2025-01-31"` + - `:completed` - - `:o1` + - `type: :apply_patch_call` - - `:"o1-2024-12-17"` + The type of the item. Always `apply_patch_call`. - - `:"gpt-4o"` + - `:apply_patch_call` - - `:"gpt-4o-2024-11-20"` + - `id: String` - - `:"gpt-4o-2024-08-06"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `:"gpt-4o-2024-05-13"` + - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - `:"gpt-4-turbo"` + The execution context that produced this tool call. - - `:"gpt-4-turbo-2024-04-09"` + - `class Direct` - - `:"gpt-4-0125-preview"` + - `type: :direct` - - `:"gpt-4-turbo-preview"` + The caller type. Always `direct`. - - `:"gpt-4-1106-preview"` + - `:direct` - - `:"gpt-4-vision-preview"` + - `class Program` - - `:"gpt-4"` + - `caller_id: String` - - `:"gpt-4-0314"` + The call ID of the program item that produced this tool call. - - `:"gpt-4-0613"` + - `type: :program` - - `:"gpt-4-32k"` + The caller type. Always `program`. - - `:"gpt-4-32k-0314"` + - `:program` - - `:"gpt-4-32k-0613"` + - `class ApplyPatchCallOutput` - - `:"gpt-3.5-turbo"` + The streamed output emitted by an apply patch tool call. - - `:"gpt-3.5-turbo-16k"` + - `call_id: String` - - `:"gpt-3.5-turbo-0613"` + The unique ID of the apply patch tool call generated by the model. - - `:"gpt-3.5-turbo-1106"` + - `status: :completed | :failed` - - `:"gpt-3.5-turbo-0125"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `:"gpt-3.5-turbo-16k-0613"` + - `:completed` -- `name: String` + - `:failed` - The name of the assistant. The maximum length is 256 characters. + - `type: :apply_patch_call_output` -- `reasoning_effort: ReasoningEffort` + The type of the item. Always `apply_patch_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. + - `:apply_patch_call_output` - - `:none` + - `id: String` - - `:minimal` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `:low` + - `agent: Agent{ agent_name}` - - `:medium` + The agent that produced this item. - - `:high` + - `agent_name: String` - - `:xhigh` + The canonical name of the agent that produced this item. - - `:max` + - `caller_: Direct{ type} | Program{ 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`. + - `class 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](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` - - `AssistantResponseFormatOption = :auto` + - `class Program` - `auto` is the default value + - `caller_id: String` - - `:auto` + The call ID of the program item that produced this tool call. - - `class ResponseFormatText` + - `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`. + - `output: String` - - `:text` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `class ResponseFormatJSONObject` + - `class McpListTools` - 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` + - `id: String` - The type of response format being defined. Always `json_object`. + The unique ID of the list. - - `:json_object` + - `server_label: String` - - `class ResponseFormatJSONSchema` + The label of the MCP server. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `json_schema: JSONSchema{ name, description, schema, strict}` + The tools available on the server. - Structured Outputs configuration options, including a JSON Schema. + - `input_schema: untyped` + + The JSON schema describing the tool's input. - `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 tool. + + - `annotations: untyped` + + Additional annotations about the tool. - `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 tool. - - `schema: Hash[Symbol, untyped]` + - `type: :mcp_list_tools` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the item. Always `mcp_list_tools`. - - `strict: bool` + - `:mcp_list_tools` - 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: Agent{ 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. -- `temperature: Float` + - `error: 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. + Error message if the server could not list tools. -- `tool_resources: ToolResources{ code_interpreter, file_search}` + - `class McpApprovalRequest` - 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. + A request for human approval of a tool invocation. - - `code_interpreter: CodeInterpreter{ file_ids}` + - `id: String` - - `file_ids: Array[String]` + The unique ID of the approval request. - 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. + - `arguments: String` - - `file_search: FileSearch{ vector_store_ids}` + A JSON string of arguments for the tool. - - `vector_store_ids: Array[String]` + - `name: String` - 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. + The name of the tool to run. -- `tools: Array[untyped]` + - `server_label: 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 label of the MCP server making the request. -- `top_p: Float` + - `type: :mcp_approval_request` - 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 `mcp_approval_request`. - We generally recommend altering this or temperature but not both. + - `:mcp_approval_request` -### Returns + - `agent: Agent{ agent_name}` -- `class Assistant` + The agent that produced this item. - Represents an `assistant` that can call the model and use tools. + - `agent_name: String` - - `id: String` + The canonical name of the agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `class McpApprovalResponse` - - `created_at: Integer` + A response to an MCP approval request. - The Unix timestamp (in seconds) for when the assistant was created. + - `approval_request_id: String` - - `description: String` + The ID of the approval request being answered. - The description of the assistant. The maximum length is 512 characters. + - `approve: bool` - - `instructions: String` + Whether the request was approved. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `type: :mcp_approval_response` - - `metadata: Metadata` + The type of the item. Always `mcp_approval_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. + - `:mcp_approval_response` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: String` - - `model: String` + The unique ID of the approval response - 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. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the assistant. The maximum length is 256 characters. + - `agent_name: String` - - `object: :assistant` + The canonical name of the agent that produced this item. - The object type, which is always `assistant`. + - `reason: String` - - `:assistant` + Optional reason for the decision. - - `tools: Array[untyped]` + - `class McpCall` - 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`. + An invocation of a tool on an MCP server. - - `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 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). + - `arguments: String` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + A JSON string of the arguments passed to the tool. - **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. + - `name: String` - - `AssistantResponseFormatOption = :auto` + The name of the tool that was run. - `auto` is the default value + - `server_label: String` - - `:auto` + The label of the MCP server running the tool. - - `class ResponseFormatText` + - `type: :mcp_call` - Default response format. Used to generate text responses. + The type of the item. Always `mcp_call`. - - `type: :text` + - `:mcp_call` - The type of response format being defined. Always `text`. + - `agent: Agent{ agent_name}` - - `:text` + The agent that produced this item. - - `class ResponseFormatJSONObject` + - `agent_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 canonical name of the agent that produced this item. - - `type: :json_object` + - `approval_request_id: String` - The type of response format being defined. Always `json_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. - - `:json_object` + - `error: String` - - `class ResponseFormatJSONSchema` + The error from the tool call, if any. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `output: String` - - `json_schema: JSONSchema{ name, description, schema, strict}` + The output from the tool call. - Structured Outputs configuration options, including a JSON Schema. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `name: String` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `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: String` + - `:completed` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:incomplete` - - `schema: Hash[Symbol, untyped]` + - `:calling` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `:failed` - - `strict: bool` + - `class BetaResponseCustomToolCallOutput` - 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 output of a custom tool call from your code, being sent back to the model. - - `type: :json_schema` + - `call_id: String` - The type of response format being defined. Always `json_schema`. + The call ID, used to map this custom tool call output to a custom tool call. - - `:json_schema` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `temperature: Float` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `String = String` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + A string of the output of the custom tool call. - 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. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `code_interpreter: CodeInterpreter{ file_ids}` + Text, image, or file output of the custom tool call. - - `file_ids: Array[String]` + - `class BetaResponseInputText` - 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. + A text input to the model. - - `file_search: FileSearch{ vector_store_ids}` + - `class BetaResponseInputImage` - - `vector_store_ids: Array[String]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - 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. + - `class BetaResponseInputFile` - - `top_p: Float` + A file input to the model. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `type: :custom_tool_call_output` - We generally recommend altering this or temperature but not both. + The type of the custom tool call output. Always `custom_tool_call_output`. -### Example + - `:custom_tool_call_output` -```ruby -require "openai" + - `id: String` -openai = OpenAI::Client.new(api_key: "My API Key") + The unique ID of the custom tool call output in the OpenAI platform. -assistant = openai.beta.assistants.update("assistant_id") + - `agent: Agent{ agent_name}` -puts(assistant) -``` + The agent that produced this item. -#### Response + - `agent_name: String` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + The canonical name of the agent that produced this item. -## Delete assistant + - `caller_: Direct{ type} | Program{ caller_id, type}` -`beta.assistants.delete(assistant_id) -> AssistantDeleted` + The execution context that produced this tool call. -**delete** `/assistants/{assistant_id}` + - `class Direct` -Delete assistant + - `type: :direct` -### Parameters + The caller type. Always `direct`. -- `assistant_id: String` + - `:direct` -### Returns + - `class Program` -- `class AssistantDeleted` + - `caller_id: String` - - `id: String` + The call ID of the program item that produced this tool call. - - `deleted: bool` + - `type: :program` - - `object: :"assistant.deleted"` + The caller type. Always `program`. - - `:"assistant.deleted"` + - `:program` -### Example + - `class BetaResponseCustomToolCall` -```ruby -require "openai" + A call to a custom tool created by the model. -openai = OpenAI::Client.new(api_key: "My API Key") + - `call_id: String` -assistant_deleted = openai.beta.assistants.delete("assistant_id") + An identifier used to map this custom tool call to a tool call output. -puts(assistant_deleted) -``` + - `input: String` -#### Response + The input for the custom tool call generated by the model. -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` + - `name: String` -## Domain Types + The name of the custom tool being called. -### Assistant + - `type: :custom_tool_call` -- `class Assistant` + The type of the custom tool call. Always `custom_tool_call`. - Represents an `assistant` that can call the model and use tools. + - `:custom_tool_call` - `id: String` - The identifier, which can be referenced in API endpoints. - - - `created_at: Integer` - - The Unix timestamp (in seconds) for when the assistant was created. - - - `description: String` - - The description of the assistant. The maximum length is 512 characters. - - - `instructions: String` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - - - `metadata: Metadata` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The unique ID of the custom tool call in the OpenAI platform. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `agent: Agent{ agent_name}` - - `model: String` + The agent that produced this item. - 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. + - `agent_name: String` - - `name: String` + The canonical name of the agent that produced this item. - The name of the assistant. The maximum length is 256 characters. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `object: :assistant` + The execution context that produced this tool call. - The object type, which is always `assistant`. + - `class Direct` - - `:assistant` + - `type: :direct` - - `tools: Array[untyped]` + - `:direct` - 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`. + - `class Program` - - `response_format: AssistantResponseFormatOption` + - `caller_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 call ID of the program item that produced this 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). + - `type: :program` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `:program` - **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. + - `namespace: String` - - `AssistantResponseFormatOption = :auto` + The namespace of the custom tool being called. - `auto` is the default value + - `class CompactionTrigger` - - `:auto` + Compacts the current context. Must be the final input item. - - `class ResponseFormatText` + - `type: :compaction_trigger` - Default response format. Used to generate text responses. + The type of the item. Always `compaction_trigger`. - - `type: :text` + - `:compaction_trigger` - The type of response format being defined. Always `text`. + - `agent: Agent{ agent_name}` - - `:text` + The agent that produced this item. - - `class ResponseFormatJSONObject` + - `agent_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 canonical name of the agent that produced this item. - - `type: :json_object` + - `class ItemReference` - The type of response format being defined. Always `json_object`. + An internal identifier for an item to reference. - - `:json_object` + - `id: String` - - `class ResponseFormatJSONSchema` + The ID of the item to reference. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: Agent{ agent_name}` - - `json_schema: JSONSchema{ name, description, schema, strict}` + The agent that produced this item. - Structured Outputs configuration options, including a JSON Schema. + - `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. + - `type: :item_reference` - - `description: String` + The type of item to reference. Always `item_reference`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:item_reference` - - `schema: Hash[Symbol, untyped]` + - `class Program` - 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` - - `strict: bool` + The unique ID of this 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](https://platform.openai.com/docs/guides/structured-outputs). + - `call_id: String` - - `type: :json_schema` + The stable call ID of the program item. - The type of response format being defined. Always `json_schema`. + - `code: String` - - `:json_schema` + The JavaScript source executed by programmatic tool calling. - - `temperature: Float` + - `fingerprint: 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. + Opaque program replay fingerprint that must be round-tripped. - - `tool_resources: ToolResources{ code_interpreter, file_search}` + - `type: :program` - 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 item type. Always `program`. - - `code_interpreter: CodeInterpreter{ file_ids}` + - `:program` - - `file_ids: Array[String]` + - `agent: Agent{ agent_name}` - 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. + The agent that produced this item. - - `file_search: FileSearch{ vector_store_ids}` + - `agent_name: String` - - `vector_store_ids: Array[String]` + The canonical name of the agent that produced this item. - 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. + - `class ProgramOutput` - - `top_p: Float` + - `id: String` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + The unique ID of this program output item. - We generally recommend altering this or temperature but not both. + - `call_id: String` -### Assistant Deleted + The call ID of the program item. -- `class AssistantDeleted` + - `result: String` - - `id: String` + The result produced by the program item. - - `deleted: bool` + - `status: :completed | :incomplete` - - `object: :"assistant.deleted"` + The terminal status of the program output. - - `:"assistant.deleted"` + - `:completed` -### Assistant Stream Event + - `:incomplete` -- `AssistantStreamEvent = ThreadCreated{ data, event, enabled} | ThreadRunCreated{ data, event} | ThreadRunQueued{ data, event} | 21 more` + - `type: :program_output` - Represents an event emitted when streaming a Run. + The item type. Always `program_output`. - Each event in a server-sent events stream has an `event` and `data` property: + - `:program_output` - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` + - `agent: Agent{ agent_name}` - 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. + The agent that produced this item. - 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. + - `agent_name: String` - - `class ThreadCreated` + The canonical name of the agent that produced this item. - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. +- `instructions: String` - - `data: Thread` + A system (or developer) message inserted into the model's context. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + 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. - - `id: String` +- `max_output_tokens: Integer` - The identifier, which can be referenced in API endpoints. + 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). - - `created_at: Integer` +- `max_tool_calls: Integer` - The Unix timestamp (in seconds) for when the thread was created. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `metadata: Metadata` +- `metadata: Hash[Symbol, 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 @@ -4370,1986 +3928,2078 @@ puts(assistant_deleted) Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `object: :thread` +- `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - The object type, which is always `thread`. + 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. - - `:thread` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + 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 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. + - `:"gpt-5.6-sol"` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `:"gpt-5.6-terra"` - - `file_ids: Array[String]` + - `:"gpt-5.6-luna"` - 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. + - `:"gpt-5.4"` - - `file_search: FileSearch{ vector_store_ids}` + - `:"gpt-5.4-mini"` - - `vector_store_ids: Array[String]` + - `:"gpt-5.4-nano"` - 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. + - `:"gpt-5.4-mini-2026-03-17"` - - `event: :"thread.created"` + - `:"gpt-5.4-nano-2026-03-17"` - - `:"thread.created"` + - `:"gpt-5.3-chat-latest"` - - `enabled: bool` + - `:"gpt-5.2"` - Whether to enable input audio transcription. + - `:"gpt-5.2-2025-12-11"` - - `class ThreadRunCreated` + - `:"gpt-5.2-chat-latest"` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `:"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"` - - `id: String` + - `:"gpt-5.1-2025-11-13"` - The identifier, which can be referenced in API endpoints. + - `:"gpt-5.1-codex"` - - `assistant_id: String` + - `:"gpt-5.1-mini"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `:"gpt-5.1-chat-latest"` - - `cancelled_at: Integer` + - `:"gpt-5"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `:"gpt-5-mini"` - - `completed_at: Integer` + - `:"gpt-5-nano"` - The Unix timestamp (in seconds) for when the run was completed. + - `:"gpt-5-2025-08-07"` - - `created_at: Integer` + - `:"gpt-5-mini-2025-08-07"` - The Unix timestamp (in seconds) for when the run was created. + - `:"gpt-5-nano-2025-08-07"` - - `expires_at: Integer` + - `:"gpt-5-chat-latest"` - The Unix timestamp (in seconds) for when the run will expire. + - `:"gpt-4.1"` - - `failed_at: Integer` + - `:"gpt-4.1-mini"` - The Unix timestamp (in seconds) for when the run failed. + - `:"gpt-4.1-nano"` - - `incomplete_details: IncompleteDetails{ reason}` + - `:"gpt-4.1-2025-04-14"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `:"gpt-4.1-mini-2025-04-14"` - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `:"gpt-4.1-nano-2025-04-14"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `:"o4-mini"` - - `:max_completion_tokens` + - `:"o4-mini-2025-04-16"` - - `:max_prompt_tokens` + - `:o3` - - `instructions: String` + - `:"o3-2025-04-16"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:"o3-mini"` - - `last_error: LastError{ code, message}` + - `:"o3-mini-2025-01-31"` - The last error associated with this run. Will be `null` if there are no errors. + - `:o1` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `:"o1-2024-12-17"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `:"o1-preview"` - - `:server_error` + - `:"o1-preview-2024-09-12"` - - `:rate_limit_exceeded` + - `:"o1-mini"` - - `:invalid_prompt` + - `:"o1-mini-2024-09-12"` - - `message: String` + - `:"gpt-4o"` - A human-readable description of the error. + - `:"gpt-4o-2024-11-20"` - - `max_completion_tokens: Integer` + - `:"gpt-4o-2024-08-06"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `:"gpt-4o-2024-05-13"` - - `max_prompt_tokens: Integer` + - `:"gpt-4o-audio-preview"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `:"gpt-4o-audio-preview-2024-10-01"` - - `metadata: Metadata` + - `:"gpt-4o-audio-preview-2024-12-17"` - Set of 16 key-value pairs that can be attached to an object. 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-audio-preview-2025-06-03"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:"gpt-4o-mini-audio-preview"` - - `model: String` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:"gpt-4o-search-preview"` - - `object: :"thread.run"` + - `:"gpt-4o-mini-search-preview"` - The object type, which is always `thread.run`. + - `:"gpt-4o-search-preview-2025-03-11"` - - `:"thread.run"` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - - `parallel_tool_calls: bool` + - `:"chatgpt-4o-latest"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `:"codex-mini-latest"` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + - `:"gpt-4o-mini"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `:"gpt-4o-mini-2024-07-18"` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + - `:"gpt-4-turbo"` - Details on the tool outputs needed for this run to continue. + - `:"gpt-4-turbo-2024-04-09"` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + - `:"gpt-4-0125-preview"` - A list of the relevant tool calls. + - `:"gpt-4-turbo-preview"` - - `id: String` + - `:"gpt-4-1106-preview"` - 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. + - `:"gpt-4-vision-preview"` - - `function: Function{ arguments, name}` + - `:"gpt-4"` - The function definition. + - `:"gpt-4-0314"` - - `arguments: String` + - `:"gpt-4-0613"` - The arguments that the model expects you to pass to the function. + - `:"gpt-4-32k"` - - `name: String` + - `:"gpt-4-32k-0314"` - The name of the function. + - `:"gpt-4-32k-0613"` - - `type: :function` + - `:"gpt-3.5-turbo"` - The type of tool call the output is required for. For now, this is always `function`. + - `:"gpt-3.5-turbo-16k"` - - `:function` + - `:"gpt-3.5-turbo-0301"` - - `type: :submit_tool_outputs` + - `:"gpt-3.5-turbo-0613"` - For now, this is always `submit_tool_outputs`. + - `:"gpt-3.5-turbo-1106"` - - `:submit_tool_outputs` + - `:"gpt-3.5-turbo-0125"` - - `response_format: AssistantResponseFormatOption` + - `:"gpt-3.5-turbo-16k-0613"` - 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`. + - `:"o1-pro"` - 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). + - `:"o1-pro-2025-03-19"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `:"o3-pro"` - **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. + - `:"o3-pro-2025-06-10"` - - `AssistantResponseFormatOption = :auto` + - `:"o3-deep-research"` - `auto` is the default value + - `:"o3-deep-research-2025-06-26"` - - `:auto` + - `:"o4-mini-deep-research"` - - `class ResponseFormatText` + - `:"o4-mini-deep-research-2025-06-26"` - Default response format. Used to generate text responses. + - `:"computer-use-preview"` - - `type: :text` + - `:"computer-use-preview-2025-03-11"` - The type of response format being defined. Always `text`. + - `:"gpt-5-codex"` - - `:text` + - `:"gpt-5-pro"` - - `class ResponseFormatJSONObject` + - `:"gpt-5-pro-2025-10-06"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `:"gpt-5.1-codex-max"` - - `type: :json_object` + - `String = String` - The type of response format being defined. Always `json_object`. +- `moderation: Moderation{ model, policy}` - - `:json_object` + Configuration for running moderation on the input and output of this response. - - `class ResponseFormatJSONSchema` + - `model: 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 moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `policy: Policy{ input, output}` - Structured Outputs configuration options, including a JSON Schema. + The policy to apply to moderated response input and output. - - `name: String` + - `input: Input{ mode}` - 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 moderation policy for the response input. - - `description: String` + - `mode: :score | :block` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:score` - - `schema: Hash[Symbol, untyped]` + - `:block` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `output: Output{ mode}` - - `strict: bool` + The moderation policy for the response 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). + - `mode: :score | :block` - - `type: :json_schema` + - `:score` - The type of response format being defined. Always `json_schema`. + - `:block` - - `:json_schema` +- `multi_agent: MultiAgent{ enabled, max_concurrent_subagents}` - - `started_at: Integer` + Configuration for server-hosted multi-agent execution. - The Unix timestamp (in seconds) for when the run was started. + - `enabled: bool` - - `status: untyped` + Whether to enable server-hosted multi-agent execution for this response. - - `thread_id: String` + - `max_concurrent_subagents: Integer` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + `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. - - `tool_choice: AssistantToolChoiceOption` +- `parallel_tool_calls: bool` - 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. + Whether to allow the model to run tool calls in parallel. - - `Auto = :none | :auto | :required` +- `previous_response_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 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`. - - `:none` +- `prompt: BetaResponsePrompt` - - `:auto` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `:required` + - `id: String` - - `class AssistantToolChoice` + The unique identifier of the prompt template to use. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `type: :function | :code_interpreter | :file_search` + 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 tool. If type is `function`, the function name must be set + - `String = String` - - `:function` + - `class BetaResponseInputText` - - `:code_interpreter` + A text input to the model. - - `:file_search` + - `class BetaResponseInputImage` - - `function: AssistantToolChoiceFunction` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `name: String` + - `class BetaResponseInputFile` - The name of the function to call. + A file input to the model. - - `tools: Array[untyped]` + - `version: String` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Optional version of the prompt template. - - `truncation_strategy: TruncationStrategy{ type, last_messages}` +- `prompt_cache_key: String` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + 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). - - `type: :auto | :last_messages` +- `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - 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`. + 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. - - `:auto` + - `mode: :implicit | :explicit` - - `:last_messages` + 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. - - `last_messages: Integer` + - `:implicit` - The number of most recent messages from the thread when constructing the context for the run. + - `:explicit` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `ttl: :"30m"` - 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 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. - - `completion_tokens: Integer` + - `:"30m"` - Number of completion tokens used over the course of the run. +- `prompt_cache_retention: :in_memory | :"24h"` - - `prompt_tokens: Integer` + Deprecated. Use `prompt_cache_options.ttl` instead. - Number of prompt tokens used over the course of the run. + 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. - - `total_tokens: Integer` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - Total number of tokens used (prompt + completion). + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `temperature: Float` + - `:in_memory` - The sampling temperature used for this run. If not set, defaults to 1. + - `:"24h"` - - `top_p: Float` +- `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - The nucleus sampling value used for this run. If not set, defaults to 1. + **gpt-5 and o-series models only** - - `event: :"thread.run.created"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `:"thread.run.created"` + - `context: :auto | :current_turn | :all_turns` - - `class ThreadRunQueued` + 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. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + - `:auto` - - `data: Run` + - `:current_turn` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:all_turns` - - `event: :"thread.run.queued"` + - `effort: :none | :minimal | :low | 4 more` - - `:"thread.run.queued"` + 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. - - `class ThreadRunInProgress` + - `:none` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + - `:minimal` - - `data: Run` + - `:low` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:medium` - - `event: :"thread.run.in_progress"` + - `:high` - - `:"thread.run.in_progress"` + - `:xhigh` - - `class ThreadRunRequiresAction` + - `:max` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `generate_summary: :auto | :concise | :detailed` - - `data: Run` + **Deprecated:** use `summary` instead. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + 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`. - - `event: :"thread.run.requires_action"` + - `:auto` - - `:"thread.run.requires_action"` + - `:concise` - - `class ThreadRunCompleted` + - `:detailed` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + - `mode: String | :standard | :pro` - - `data: Run` + Controls the reasoning execution mode for the request. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + When returned on a response, this is the effective execution mode. - - `event: :"thread.run.completed"` + - `String = String` - - `:"thread.run.completed"` + - `Mode = :standard | :pro` - - `class ThreadRunIncomplete` + Controls the reasoning execution mode for the request. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + When returned on a response, this is the effective execution mode. - - `data: Run` + - `:standard` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:pro` - - `event: :"thread.run.incomplete"` + - `summary: :auto | :concise | :detailed` - - `:"thread.run.incomplete"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `class ThreadRunFailed` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `:auto` - - `data: Run` + - `:concise` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:detailed` - - `event: :"thread.run.failed"` +- `safety_identifier: String` - - `:"thread.run.failed"` + 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). - - `class ThreadRunCancelling` +- `service_tier: :auto | :default | :flex | 2 more` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + Specifies the processing type used for serving the request. - - `data: Run` + - 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'. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + 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. - - `event: :"thread.run.cancelling"` + - `:auto` - - `:"thread.run.cancelling"` + - `:default` - - `class ThreadRunCancelled` + - `:flex` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + - `:scale` - - `data: Run` + - `:priority` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). +- `store: bool` - - `event: :"thread.run.cancelled"` + Whether to store the generated model response for later retrieval via + API. - - `:"thread.run.cancelled"` +- `stream: bool` - - `class ThreadRunExpired` + 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. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. +- `stream_options: StreamOptions{ include_obfuscation}` - - `data: Run` + Options for streaming responses. Only set this when you set `stream: true`. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `include_obfuscation: bool` - - `event: :"thread.run.expired"` + 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. - - `:"thread.run.expired"` +- `temperature: Float` - - `class ThreadRunStepCreated` + 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. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. +- `text: BetaResponseTextConfig` - - `data: RunStep` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - Represents a step in execution of a run. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `id: String` + - `format_: BetaResponseFormatTextConfig` - The identifier of the run step, which can be referenced in API endpoints. + An object specifying the format that the model must output. - - `assistant_id: String` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The default format is `{ "type": "text" }` with no additional options. - - `cancelled_at: Integer` + **Not recommended for gpt-4o and newer models:** - The Unix timestamp (in seconds) for when the run step was cancelled. + 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. - - `completed_at: Integer` + - `class Text` - The Unix timestamp (in seconds) for when the run step completed. + Default response format. Used to generate text responses. - - `created_at: Integer` + - `type: :text` - The Unix timestamp (in seconds) for when the run step was created. + The type of response format being defined. Always `text`. - - `expired_at: Integer` + - `:text` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `class BetaResponseFormatTextJSONSchemaConfig` - - `failed_at: Integer` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The Unix timestamp (in seconds) for when the run step failed. + - `name: String` - - `last_error: LastError{ code, 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. - The last error associated with this run step. Will be `null` if there are no errors. + - `schema: Hash[Symbol, untyped]` - - `code: :server_error | :rate_limit_exceeded` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - One of `server_error` or `rate_limit_exceeded`. + - `type: :json_schema` - - `:server_error` + The type of response format being defined. Always `json_schema`. - - `:rate_limit_exceeded` + - `:json_schema` - - `message: String` + - `description: String` - A human-readable description of the error. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `metadata: Metadata` + - `strict: bool` - Set of 16 key-value pairs that can be attached to an object. 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 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). - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class JSONObject` - - `object: :"thread.run.step"` + 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 object type, which is always `thread.run.step`. + - `type: :json_object` - - `:"thread.run.step"` + The type of response format being defined. Always `json_object`. - - `run_id: String` + - `:json_object` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `verbosity: :low | :medium | :high` - - `status: :in_progress | :cancelled | :failed | 2 more` + 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 status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `:low` - - `:in_progress` + - `:medium` - - `:cancelled` + - `:high` - - `:failed` +- `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `:completed` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `:expired` + - `BetaToolChoiceOptions = :none | :auto | :required` - - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` + Controls which (if any) tool is called by the model. - The details of the run step. + `none` means the model will not call any tool and instead generates a message. - - `class MessageCreationStepDetails` + `auto` means the model can pick between generating a message or calling one or + more tools. - Details of the message creation by the run step. + `required` means the model must call one or more tools. - - `message_creation: MessageCreation{ message_id}` + - `:none` - - `message_id: String` + - `:auto` - The ID of the message that was created by this run step. + - `:required` - - `type: :message_creation` + - `class BetaToolChoiceAllowed` - Always `message_creation`. + Constrains the tools available to the model to a pre-defined set. - - `:message_creation` + - `mode: :auto | :required` - - `class ToolCallsStepDetails` + Constrains the tools available to the model to a pre-defined set. - Details of the tool call. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `tool_calls: Array[untyped]` + `required` requires the model to call one or more of the allowed tools. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `:auto` - - `type: :tool_calls` + - `:required` - Always `tool_calls`. + - `tools: Array[Hash[Symbol, untyped]]` - - `:tool_calls` + A list of tool definitions that the model should be allowed to call. - - `thread_id: String` + For the Responses API, the list of tool definitions might look like: - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `type: :message_creation | :tool_calls` + - `type: :allowed_tools` - The type of run step, which can be either `message_creation` or `tool_calls`. + Allowed tool configuration type. Always `allowed_tools`. - - `:message_creation` + - `:allowed_tools` - - `:tool_calls` + - `class BetaToolChoiceTypes` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + 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). - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `completion_tokens: Integer` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - Number of completion tokens used over the course of the run step. + Allowed values are: - - `prompt_tokens: Integer` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Number of prompt tokens used over the course of the run step. + - `:file_search` - - `total_tokens: Integer` + - `:web_search_preview` - Total number of tokens used (prompt + completion). + - `:computer` - - `event: :"thread.run.step.created"` + - `:computer_use_preview` - - `:"thread.run.step.created"` + - `:computer_use` - - `class ThreadRunStepInProgress` + - `:web_search_preview_2025_03_11` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `:image_generation` - - `data: RunStep` + - `:code_interpreter` - Represents a step in execution of a run. + - `class BetaToolChoiceFunction` - - `event: :"thread.run.step.in_progress"` + Use this option to force the model to call a specific function. - - `:"thread.run.step.in_progress"` + - `name: String` - - `class ThreadRunStepDelta` + The name of the function to call. - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `type: :function` - - `data: RunStepDeltaEvent` + For function calling, the type is always `function`. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `:function` - - `id: String` + - `class BetaToolChoiceMcp` - The identifier of the run step, which can be referenced in API endpoints. + Use this option to force the model to call a specific tool on a remote MCP server. - - `delta: untyped` + - `server_label: String` - - `object: :"thread.run.step.delta"` + The label of the MCP server to use. - The object type, which is always `thread.run.step.delta`. + - `type: :mcp` - - `:"thread.run.step.delta"` + For MCP tools, the type is always `mcp`. - - `event: :"thread.run.step.delta"` + - `:mcp` - - `:"thread.run.step.delta"` + - `name: String` - - `class ThreadRunStepCompleted` + The name of the tool to call on the server. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + - `class BetaToolChoiceCustom` - - `data: RunStep` + Use this option to force the model to call a specific custom tool. - Represents a step in execution of a run. + - `name: String` - - `event: :"thread.run.step.completed"` + The name of the custom tool to call. - - `:"thread.run.step.completed"` + - `type: :custom` - - `class ThreadRunStepFailed` + For custom tool calling, the type is always `custom`. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + - `:custom` - - `data: RunStep` + - `class BetaSpecificProgrammaticToolCallingParam` - Represents a step in execution of a run. + - `type: :programmatic_tool_calling` - - `event: :"thread.run.step.failed"` + The tool to call. Always `programmatic_tool_calling`. - - `:"thread.run.step.failed"` + - `:programmatic_tool_calling` - - `class ThreadRunStepCancelled` + - `class BetaToolChoiceApplyPatch` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + Forces the model to call the apply_patch tool when executing a tool call. - - `data: RunStep` + - `type: :apply_patch` - Represents a step in execution of a run. + The tool to call. Always `apply_patch`. - - `event: :"thread.run.step.cancelled"` + - `:apply_patch` - - `:"thread.run.step.cancelled"` + - `class BetaToolChoiceShell` - - `class ThreadRunStepExpired` + Forces the model to call the shell tool when a tool call is required. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + - `type: :shell` - - `data: RunStep` + The tool to call. Always `shell`. - Represents a step in execution of a run. + - `:shell` - - `event: :"thread.run.step.expired"` +- `tools: Array[BetaTool]` - - `:"thread.run.step.expired"` + 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. - - `class ThreadMessageCreated` + We support the following categories of tools: - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - **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. - - `data: Message` + - `class BetaFunctionTool` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `id: String` + - `class BetaFileSearchTool` - The identifier, which can be referenced in API endpoints. + 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). - - `assistant_id: String` + - `class BetaComputerTool` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `attachments: Array[Attachment{ file_id, tools}]` + - `class BetaComputerUsePreviewTool` - A list of files attached to the message, and the tools they were added to. + 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` + - `class BetaWebSearchTool` - The ID of the file to attach to the message. + 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). - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + - `class Mcp` - The tools to add this file to. + 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). - - `class CodeInterpreterTool` + - `class CodeInterpreter` - - `type: :code_interpreter` + A tool that runs Python code to help generate a response to a prompt. - The type of tool being defined: `code_interpreter` + - `class ProgrammaticToolCalling` - - `:code_interpreter` + - `class ImageGeneration` - - `class AssistantToolsFileSearchTypeOnly` + A tool that generates images using the GPT image models. - - `type: :file_search` + - `class LocalShell` - The type of tool being defined: `file_search` + A tool that allows the model to execute shell commands in a local environment. - - `:file_search` + - `class BetaFunctionShellTool` - - `completed_at: Integer` + A tool that allows the model to execute shell commands. - The Unix timestamp (in seconds) for when the message was completed. + - `class BetaCustomTool` - - `content: Array[untyped]` + 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 content of the message in array of text and/or images. + - `class BetaNamespaceTool` - - `created_at: Integer` + Groups function/custom tools under a shared namespace. - The Unix timestamp (in seconds) for when the message was created. + - `class BetaToolSearchTool` - - `incomplete_at: Integer` + Hosted or BYOT tool search configuration for deferred tools. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `class BetaWebSearchPreviewTool` - - `incomplete_details: IncompleteDetails{ reason}` + 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). - On an incomplete message, details about why the message is incomplete. + - `class BetaApplyPatchTool` - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + Allows the assistant to create, delete, or update files using unified diffs. - The reason the message is incomplete. +- `top_logprobs: Integer` - - `:content_filter` + 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. - - `:max_tokens` +- `top_p: Float` - - `:run_cancelled` + 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. - - `:run_expired` + We generally recommend altering this or `temperature` but not both. - - `:run_failed` +- `truncation: :auto | :disabled` - - `metadata: Metadata` + The truncation strategy to use for the model 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. + - `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. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:auto` - - `object: :"thread.message"` + - `:disabled` - The object type, which is always `thread.message`. +- `user: String` - - `:"thread.message"` + 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). - - `role: :user | :assistant` +- `betas: Array[:"responses_multi_agent=v1"]` - The entity that produced the message. One of `user` or `assistant`. + - `:"responses_multi_agent=v1"` - - `:user` +### Returns - - `:assistant` +- `class BetaResponse` - - `run_id: String` + - `id: 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. + Unique identifier for this Response. - - `status: :in_progress | :incomplete | :completed` + - `created_at: Float` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + Unix timestamp (in seconds) of when this Response was created. - - `:in_progress` + - `error: BetaResponseError` - - `:incomplete` + An error object returned when the model fails to generate a Response. - - `:completed` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `thread_id: String` + The error code for the response. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `:server_error` - - `event: :"thread.message.created"` + - `:rate_limit_exceeded` - - `:"thread.message.created"` + - `:invalid_prompt` - - `class ThreadMessageInProgress` + - `:bio_policy` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + - `:vector_store_timeout` - - `data: Message` + - `:invalid_image` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:invalid_image_format` - - `event: :"thread.message.in_progress"` + - `:invalid_base64_image` - - `:"thread.message.in_progress"` + - `:invalid_image_url` - - `class ThreadMessageDelta` + - `:image_too_large` - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `:image_too_small` - - `data: MessageDeltaEvent` + - `:image_parse_error` - Represents a message delta i.e. any changed fields on a message during streaming. + - `:image_content_policy_violation` - - `id: String` + - `:invalid_image_mode` - The identifier of the message, which can be referenced in API endpoints. + - `:image_file_too_large` - - `delta: MessageDelta` + - `:unsupported_image_media_type` - The delta containing the fields that have changed on the Message. + - `:empty_image_file` - - `content: Array[untyped]` + - `:failed_to_download_image` - The content of the message in array of text and/or images. + - `:image_file_not_found` - - `role: :user | :assistant` + - `message: String` - The entity that produced the message. One of `user` or `assistant`. + A human-readable description of the error. - - `:user` + - `incomplete_details: IncompleteDetails{ reason}` - - `:assistant` + Details about why the response is incomplete. - - `object: :"thread.message.delta"` + - `reason: :max_output_tokens | :content_filter` - The object type, which is always `thread.message.delta`. + The reason why the response is incomplete. - - `:"thread.message.delta"` + - `:max_output_tokens` - - `event: :"thread.message.delta"` + - `:content_filter` - - `:"thread.message.delta"` + - `instructions: String | Array[BetaResponseInputItem]` - - `class ThreadMessageCompleted` + A system (or developer) message inserted into the model's context. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + 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: Message` + - `String = String` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + A text input to the model, equivalent to a text input with the + `developer` role. - - `event: :"thread.message.completed"` + - `InputItemList = Array[BetaResponseInputItem]` - - `:"thread.message.completed"` + A list of one or many input items to the model, containing + different content types. - - `class ThreadMessageIncomplete` + - `class BetaEasyInputMessage` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `data: Message` + - `content: String | BetaResponseInputMessageContentList` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `event: :"thread.message.incomplete"` + - `String = String` - - `:"thread.message.incomplete"` + A text input to the model. - - `class ErrorEvent` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - 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. + A list of one or many input items to the model, containing different content + types. - - `data: ErrorObject` + - `class BetaResponseInputText` - - `code: String` + A text input to the model. - - `message: String` + - `text: String` - - `param: String` + The text input to the model. - - `type: String` + - `type: :input_text` - - `event: :error` + The type of the input item. Always `input_text`. - - `:error` + - `:input_text` -### Assistant Tool + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` -- `AssistantTool = untyped` + Marks the exact end of a reusable 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 Tool + - `mode: :explicit` -- `class CodeInterpreterTool` + The breakpoint mode. Always `explicit`. - - `type: :code_interpreter` + - `:explicit` - The type of tool being defined: `code_interpreter` + - `class BetaResponseInputImage` - - `:code_interpreter` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -### File Search Tool + - `detail: :low | :high | :auto | :original` -- `class FileSearchTool` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :file_search` + - `:low` - The type of tool being defined: `file_search` + - `:high` - - `:file_search` + - `:auto` - - `file_search: FileSearch{ max_num_results, ranking_options}` + - `:original` - Overrides for the file search tool. + - `type: :input_image` - - `max_num_results: Integer` + The type of the input item. Always `input_image`. - 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. + - `:input_image` - 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. + - `file_id: String` - - `ranking_options: RankingOptions{ score_threshold, ranker}` + The ID of the file to be sent to the model. - 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. + - `image_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 image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `score_threshold: Float` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The score threshold for the file search. All values must be a floating point number 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. - - `ranker: :auto | :default_2024_08_21` + - `mode: :explicit` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The breakpoint mode. Always `explicit`. - - `:auto` + - `:explicit` - - `:default_2024_08_21` + - `class BetaResponseInputFile` -### Function Tool + A file input to the model. -- `class FunctionTool` + - `type: :input_file` - - `function: FunctionDefinition` + The type of the input item. Always `input_file`. - - `name: String` + - `:input_file` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `detail: :auto | :low | :high` - - `description: 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`. - A description of what the function does, used by the model to choose when and how to call the function. + - `:auto` - - `parameters: FunctionParameters` + - `:low` - 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. + - `:high` - Omitting `parameters` defines a function with an empty parameter list. + - `file_data: String` - - `strict: bool` + The content of the file to be sent to 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](https://platform.openai.com/docs/guides/function-calling). + - `file_id: String` - - `type: :function` + The ID of the file to be sent to the model. - The type of tool being defined: `function` + - `file_url: String` - - `:function` + The URL of the file to be sent to the model. -### Message Stream Event + - `filename: String` -- `MessageStreamEvent = ThreadMessageCreated{ data, event} | ThreadMessageInProgress{ data, event} | ThreadMessageDelta{ data, event} | 2 more` + The name of the file to be sent to the model. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class ThreadMessageCreated` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `mode: :explicit` - - `data: Message` + The breakpoint mode. Always `explicit`. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:explicit` - - `id: String` + - `role: :user | :assistant | :system | :developer` - The identifier, which can be referenced in API endpoints. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `assistant_id: String` + - `:user` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `:assistant` - - `attachments: Array[Attachment{ file_id, tools}]` + - `:system` - A list of files attached to the message, and the tools they were added to. + - `:developer` - - `file_id: String` + - `phase: :commentary | :final_answer` - The ID of the file to attach to the message. + 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. - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + - `:commentary` - The tools to add this file to. + - `:final_answer` - - `class CodeInterpreterTool` + - `type: :message` - - `type: :code_interpreter` + The type of the message input. Always `message`. - The type of tool being defined: `code_interpreter` + - `:message` - - `:code_interpreter` + - `class Message` - - `class AssistantToolsFileSearchTypeOnly` + 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: :file_search` + - `content: BetaResponseInputMessageContentList` - The type of tool being defined: `file_search` + A list of one or many input items to the model, containing different content + types. - - `:file_search` + - `role: :user | :system | :developer` - - `completed_at: Integer` + The role of the message input. One of `user`, `system`, or `developer`. - The Unix timestamp (in seconds) for when the message was completed. + - `:user` - - `content: Array[untyped]` + - `:system` - The content of the message in array of text and/or images. + - `:developer` - - `created_at: Integer` + - `agent: Agent{ agent_name}` - The Unix timestamp (in seconds) for when the message was created. + The agent that produced this item. - - `incomplete_at: Integer` + - `agent_name: String` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The canonical name of the agent that produced this item. - - `incomplete_details: IncompleteDetails{ reason}` + - `status: :in_progress | :completed | :incomplete` - On an incomplete message, details about why the message is incomplete. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + - `:in_progress` - The reason the message is incomplete. + - `:completed` - - `:content_filter` + - `:incomplete` - - `:max_tokens` + - `type: :message` - - `:run_cancelled` + The type of the message input. Always set to `message`. - - `:run_expired` + - `:message` - - `:run_failed` + - `class BetaResponseOutputMessage` - - `metadata: Metadata` + An output message 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. + - `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 output message. - - `object: :"thread.message"` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The object type, which is always `thread.message`. + The content of the output message. - - `:"thread.message"` + - `class BetaResponseOutputText` - - `role: :user | :assistant` + A text output from the model. - The entity that produced the message. One of `user` or `assistant`. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:user` + The annotations of the text output. - - `:assistant` + - `class FileCitation` - - `run_id: String` + A citation to a file. - 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. + - `file_id: String` - - `status: :in_progress | :incomplete | :completed` + The ID of the file. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `filename: String` - - `:in_progress` + The filename of the file cited. - - `:incomplete` + - `index: Integer` - - `:completed` + The index of the file in the list of files. - - `thread_id: String` + - `type: :file_citation` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The type of the file citation. Always `file_citation`. - - `event: :"thread.message.created"` + - `:file_citation` - - `:"thread.message.created"` + - `class URLCitation` - - `class ThreadMessageInProgress` + A citation for a web resource used to generate a model response. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + - `end_index: Integer` - - `data: Message` + The index of the last character of the URL citation in the message. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `start_index: Integer` - - `event: :"thread.message.in_progress"` + The index of the first character of the URL citation in the message. - - `:"thread.message.in_progress"` + - `title: String` - - `class ThreadMessageDelta` + The title of the web resource. - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `type: :url_citation` - - `data: MessageDeltaEvent` + The type of the URL citation. Always `url_citation`. - Represents a message delta i.e. any changed fields on a message during streaming. + - `:url_citation` - - `id: String` + - `url: String` - The identifier of the message, which can be referenced in API endpoints. + The URL of the web resource. - - `delta: MessageDelta` + - `class ContainerFileCitation` - The delta containing the fields that have changed on the Message. + A citation for a container file used to generate a model response. - - `content: Array[untyped]` + - `container_id: String` - The content of the message in array of text and/or images. + The ID of the container file. - - `role: :user | :assistant` + - `end_index: Integer` - The entity that produced the message. One of `user` or `assistant`. + The index of the last character of the container file citation in the message. - - `:user` + - `file_id: String` - - `:assistant` + The ID of the file. - - `object: :"thread.message.delta"` + - `filename: String` - The object type, which is always `thread.message.delta`. + The filename of the container file cited. - - `:"thread.message.delta"` + - `start_index: Integer` - - `event: :"thread.message.delta"` + The index of the first character of the container file citation in the message. - - `:"thread.message.delta"` + - `type: :container_file_citation` - - `class ThreadMessageCompleted` + The type of the container file citation. Always `container_file_citation`. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + - `:container_file_citation` - - `data: Message` + - `class FilePath` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + A path to a file. - - `event: :"thread.message.completed"` + - `file_id: String` - - `:"thread.message.completed"` + The ID of the file. - - `class ThreadMessageIncomplete` + - `index: Integer` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + The index of the file in the list of files. - - `data: Message` + - `type: :file_path` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The type of the file path. Always `file_path`. - - `event: :"thread.message.incomplete"` + - `:file_path` - - `:"thread.message.incomplete"` + - `text: String` -### Run Step Stream Event + The text output from the model. -- `RunStepStreamEvent = ThreadRunStepCreated{ data, event} | ThreadRunStepInProgress{ data, event} | ThreadRunStepDelta{ data, event} | 4 more` + - `type: :output_text` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + The type of the output text. Always `output_text`. - - `class ThreadRunStepCreated` + - `:output_text` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `data: RunStep` + - `token: String` - Represents a step in execution of a run. + - `bytes: Array[Integer]` - - `id: String` + - `logprob: Float` - The identifier of the run step, which can be referenced in API endpoints. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `assistant_id: String` + - `token: String` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `bytes: Array[Integer]` - - `cancelled_at: Integer` + - `logprob: Float` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `class BetaResponseOutputRefusal` - - `completed_at: Integer` + A refusal from the model. - The Unix timestamp (in seconds) for when the run step completed. + - `refusal: String` - - `created_at: Integer` + The refusal explanation from the model. - The Unix timestamp (in seconds) for when the run step was created. + - `type: :refusal` - - `expired_at: Integer` + The type of the refusal. Always `refusal`. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `:refusal` - - `failed_at: Integer` + - `role: :assistant` - The Unix timestamp (in seconds) for when the run step failed. + The role of the output message. Always `assistant`. - - `last_error: LastError{ code, message}` + - `:assistant` - The last error associated with this run step. Will be `null` if there are no errors. + - `status: :in_progress | :completed | :incomplete` - - `code: :server_error | :rate_limit_exceeded` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - One of `server_error` or `rate_limit_exceeded`. + - `:in_progress` - - `:server_error` + - `:completed` - - `:rate_limit_exceeded` + - `:incomplete` - - `message: String` + - `type: :message` - A human-readable description of the error. + The type of the output message. Always `message`. - - `metadata: Metadata` + - `: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. + - `agent: Agent{ 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. - - `object: :"thread.run.step"` + - `agent_name: String` - The object type, which is always `thread.run.step`. + The canonical name of the agent that produced this item. - - `:"thread.run.step"` + - `phase: :commentary | :final_answer` - - `run_id: String` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `:commentary` - - `status: :in_progress | :cancelled | :failed | 2 more` + - `:final_answer` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `class BetaResponseFileSearchToolCall` - - `:in_progress` + 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. - - `:cancelled` + - `id: String` - - `:failed` + The unique ID of the file search tool call. - - `:completed` + - `queries: Array[String]` - - `:expired` + The queries used to search for files. - - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` + - `status: :in_progress | :searching | :completed | 2 more` - The details of the run step. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `class MessageCreationStepDetails` + - `:in_progress` - Details of the message creation by the run step. + - `:searching` - - `message_creation: MessageCreation{ message_id}` + - `:completed` - - `message_id: String` + - `:incomplete` - The ID of the message that was created by this run step. + - `:failed` - - `type: :message_creation` + - `type: :file_search_call` - Always `message_creation`. + The type of the file search tool call. Always `file_search_call`. - - `:message_creation` + - `:file_search_call` - - `class ToolCallsStepDetails` + - `agent: Agent{ agent_name}` - Details of the tool call. + The agent that produced this item. - - `tool_calls: Array[untyped]` + - `agent_name: String` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The canonical name of the agent that produced this item. - - `type: :tool_calls` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - Always `tool_calls`. + The results of the file search tool call. - - `:tool_calls` + - `attributes: Hash[Symbol, String | Float | bool]` - - `thread_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 [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `String = String` - - `type: :message_creation | :tool_calls` + - `Float = Float` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `UnionMember2 = bool` - - `:message_creation` + - `file_id: String` - - `:tool_calls` + The unique ID of the file. - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `filename: String` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The name of the file. - - `completion_tokens: Integer` + - `score: Float` - Number of completion tokens used over the course of the run step. + The relevance score of the file - a value between 0 and 1. - - `prompt_tokens: Integer` + - `text: String` - Number of prompt tokens used over the course of the run step. + The text that was retrieved from the file. - - `total_tokens: Integer` + - `class BetaResponseComputerToolCall` - Total number of tokens used (prompt + completion). + 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. - - `event: :"thread.run.step.created"` + - `id: String` - - `:"thread.run.step.created"` + The unique ID of the computer call. - - `class ThreadRunStepInProgress` + - `call_id: String` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + An identifier used when responding to the tool call with output. - - `data: RunStep` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - Represents a step in execution of a run. + The pending safety checks for the computer call. - - `event: :"thread.run.step.in_progress"` + - `id: String` - - `:"thread.run.step.in_progress"` + The ID of the pending safety check. - - `class ThreadRunStepDelta` + - `code: String` - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + The type of the pending safety check. - - `data: RunStepDeltaEvent` + - `message: String` - Represents a run step delta i.e. any changed fields on a run step during streaming. + Details about the pending safety check. - - `id: String` + - `status: :in_progress | :completed | :incomplete` - The identifier of the run step, which can be referenced in API endpoints. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `delta: untyped` + - `:in_progress` - - `object: :"thread.run.step.delta"` + - `:completed` - The object type, which is always `thread.run.step.delta`. + - `:incomplete` - - `:"thread.run.step.delta"` + - `type: :computer_call` - - `event: :"thread.run.step.delta"` + The type of the computer call. Always `computer_call`. - - `:"thread.run.step.delta"` + - `:computer_call` - - `class ThreadRunStepCompleted` + - `action: BetaComputerAction` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + A click action. - - `data: RunStep` + - `class Click` - Represents a step in execution of a run. + A click action. - - `event: :"thread.run.step.completed"` + - `button: :left | :right | :wheel | 2 more` - - `:"thread.run.step.completed"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class ThreadRunStepFailed` + - `:left` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + - `:right` - - `data: RunStep` + - `:wheel` - Represents a step in execution of a run. + - `:back` - - `event: :"thread.run.step.failed"` + - `:forward` - - `:"thread.run.step.failed"` + - `type: :click` - - `class ThreadRunStepCancelled` + Specifies the event type. For a click action, this property is always `click`. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + - `:click` - - `data: RunStep` + - `x: Integer` - Represents a step in execution of a run. + The x-coordinate where the click occurred. - - `event: :"thread.run.step.cancelled"` + - `y_: Integer` - - `:"thread.run.step.cancelled"` + The y-coordinate where the click occurred. - - `class ThreadRunStepExpired` + - `keys: Array[String]` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + The keys being held while clicking. - - `data: RunStep` + - `class DoubleClick` - Represents a step in execution of a run. + A double click action. - - `event: :"thread.run.step.expired"` + - `keys: Array[String]` - - `:"thread.run.step.expired"` + The keys being held while double-clicking. -### Run Stream Event + - `type: :double_click` -- `RunStreamEvent = ThreadRunCreated{ data, event} | ThreadRunQueued{ data, event} | ThreadRunInProgress{ data, event} | 7 more` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `:double_click` - - `class ThreadRunCreated` + - `x: Integer` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + The x-coordinate where the double click occurred. - - `data: Run` + - `y_: Integer` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The y-coordinate where the double click occurred. - - `id: String` + - `class Drag` - The identifier, which can be referenced in API endpoints. + A drag action. - - `assistant_id: String` + - `path: Array[Path{ x, y_}]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `cancelled_at: Integer` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The Unix timestamp (in seconds) for when the run was cancelled. + - `x: Integer` - - `completed_at: Integer` + The x-coordinate. - The Unix timestamp (in seconds) for when the run was completed. + - `y_: Integer` - - `created_at: Integer` + The y-coordinate. - The Unix timestamp (in seconds) for when the run was created. + - `type: :drag` - - `expires_at: Integer` + Specifies the event type. For a drag action, this property is always set to `drag`. - The Unix timestamp (in seconds) for when the run will expire. + - `:drag` - - `failed_at: Integer` + - `keys: Array[String]` - The Unix timestamp (in seconds) for when the run failed. + The keys being held while dragging the mouse. - - `incomplete_details: IncompleteDetails{ reason}` + - `class Keypress` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + A collection of keypresses the model would like to perform. - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `keys: Array[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 combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `:max_completion_tokens` + - `type: :keypress` - - `:max_prompt_tokens` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `instructions: String` + - `:keypress` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class Move` - - `last_error: LastError{ code, message}` + A mouse move action. - The last error associated with this run. Will be `null` if there are no errors. + - `type: :move` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + Specifies the event type. For a move action, this property is always set to `move`. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `:move` - - `:server_error` + - `x: Integer` - - `:rate_limit_exceeded` + The x-coordinate to move to. - - `:invalid_prompt` + - `y_: Integer` - - `message: String` + The y-coordinate to move to. - A human-readable description of the error. + - `keys: Array[String]` - - `max_completion_tokens: Integer` + The keys being held while moving the mouse. - The maximum number of completion tokens specified to have been used over the course of the run. + - `class Screenshot` - - `max_prompt_tokens: Integer` + A screenshot action. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: :screenshot` - - `metadata: Metadata` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:screenshot` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class Scroll` - - `model: String` + A scroll action. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `scroll_x: Integer` - - `object: :"thread.run"` + The horizontal scroll distance. - The object type, which is always `thread.run`. + - `scroll_y: Integer` - - `:"thread.run"` + The vertical scroll distance. - - `parallel_tool_calls: bool` + - `type: :scroll` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `required_action: RequiredAction{ submit_tool_outputs, type}` + - `:scroll` - Details on the action required to continue the run. Will be `null` if no action is required. + - `x: Integer` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + The x-coordinate where the scroll occurred. - Details on the tool outputs needed for this run to continue. + - `y_: Integer` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + The y-coordinate where the scroll occurred. - A list of the relevant tool calls. + - `keys: Array[String]` - - `id: String` + The keys being held while scrolling. - 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. + - `class Type` - - `function: Function{ arguments, name}` + An action to type in text. - The function definition. + - `text: String` - - `arguments: String` + The text to type. - The arguments that the model expects you to pass to the function. + - `type: :type` - - `name: String` + Specifies the event type. For a type action, this property is always set to `type`. - The name of the function. + - `:type` - - `type: :function` + - `class Wait` - The type of tool call the output is required for. For now, this is always `function`. + A wait action. - - `:function` + - `type: :wait` - - `type: :submit_tool_outputs` + Specifies the event type. For a wait action, this property is always set to `wait`. - For now, this is always `submit_tool_outputs`. + - `:wait` - - `:submit_tool_outputs` + - `actions: BetaComputerActionList` - - `response_format: AssistantResponseFormatOption` - - 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`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - 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). + - `class Click` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + A click action. - **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. + - `class DoubleClick` - - `AssistantResponseFormatOption = :auto` + A double click action. - `auto` is the default value + - `class Drag` - - `:auto` + A drag action. - - `class ResponseFormatText` + - `class Keypress` - Default response format. Used to generate text responses. + A collection of keypresses the model would like to perform. - - `type: :text` + - `class Move` - The type of response format being defined. Always `text`. + A mouse move action. - - `:text` + - `class Screenshot` - - `class ResponseFormatJSONObject` + A screenshot action. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `class Scroll` - - `type: :json_object` + A scroll action. - The type of response format being defined. Always `json_object`. + - `class Type` - - `:json_object` + An action to type in text. - - `class ResponseFormatJSONSchema` + - `class Wait` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A wait action. - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `agent: Agent{ agent_name}` - Structured Outputs configuration options, including a JSON Schema. + 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. - - `description: String` + - `class ComputerCallOutput` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The output of a computer tool call. - - `schema: Hash[Symbol, untyped]` + - `call_id: String` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The ID of the computer tool call that produced the output. - - `strict: bool` + - `output: BetaResponseComputerToolCallOutputScreenshot` - 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). + A computer screenshot image used with the computer use tool. - - `type: :json_schema` + - `type: :computer_screenshot` - The type of response format being defined. Always `json_schema`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:json_schema` + - `:computer_screenshot` - - `started_at: Integer` + - `file_id: String` - The Unix timestamp (in seconds) for when the run was started. + The identifier of an uploaded file that contains the screenshot. - - `status: untyped` + - `image_url: String` - - `thread_id: String` + The URL of the screenshot image. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `type: :computer_call_output` - - `tool_choice: AssistantToolChoiceOption` + The type of the computer tool call output. Always `computer_call_output`. - 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. + - `:computer_call_output` - - `Auto = :none | :auto | :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 ID of the computer tool call output. - - `:none` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:auto` + The safety checks reported by the API that have been acknowledged by the developer. - - `:required` + - `id: String` - - `class AssistantToolChoice` + The ID of the pending safety check. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `code: String` - - `type: :function | :code_interpreter | :file_search` + The type of the pending safety check. - The type of the tool. If type is `function`, the function name must be set + - `message: String` - - `:function` + Details about the pending safety check. - - `:code_interpreter` + - `agent: Agent{ agent_name}` - - `:file_search` + The agent that produced this item. - - `function: AssistantToolChoiceFunction` + - `agent_name: String` - - `name: String` + The canonical name of the agent that produced this item. - The name of the function to call. + - `status: :in_progress | :completed | :incomplete` - - `tools: Array[untyped]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:in_progress` - - `truncation_strategy: TruncationStrategy{ 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. + - `:incomplete` - - `type: :auto | :last_messages` + - `class BetaResponseFunctionWebSearch` - 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 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` - - `:last_messages` + The unique ID of the web search tool call. - - `last_messages: Integer` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - The number of most recent messages from the thread when constructing the context for the 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). - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `class Search` - 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.). + Action type "search" - Performs a web search query. - - `completion_tokens: Integer` + - `type: :search` - Number of completion tokens used over the course of the run. + The action type. - - `prompt_tokens: Integer` + - `:search` - Number of prompt tokens used over the course of the run. + - `queries: Array[String]` - - `total_tokens: Integer` + The search queries. - Total number of tokens used (prompt + completion). + - `query: String` - - `temperature: Float` + The search query. - The sampling temperature used for this run. If not set, defaults to 1. + - `sources: Array[Source{ type, url}]` - - `top_p: Float` + The sources used in the search. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: :url` - - `event: :"thread.run.created"` + The type of source. Always `url`. - - `:"thread.run.created"` + - `:url` - - `class ThreadRunQueued` + - `url: String` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + The URL of the source. - - `data: Run` + - `class OpenPage` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Action type "open_page" - Opens a specific URL from search results. - - `event: :"thread.run.queued"` + - `type: :open_page` - - `:"thread.run.queued"` + The action type. - - `class ThreadRunInProgress` + - `:open_page` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + - `url: String` - - `data: Run` + The URL opened by the model. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class FindInPage` - - `event: :"thread.run.in_progress"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `:"thread.run.in_progress"` + - `pattern: String` - - `class ThreadRunRequiresAction` + The pattern or text to search for within the page. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `type: :find_in_page` - - `data: Run` + The action type. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:find_in_page` - - `event: :"thread.run.requires_action"` + - `url: String` - - `:"thread.run.requires_action"` + The URL of the page searched for the pattern. - - `class ThreadRunCompleted` + - `status: :in_progress | :searching | :completed | :failed` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + The status of the web search tool call. - - `data: Run` + - `:in_progress` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:searching` - - `event: :"thread.run.completed"` + - `:completed` - - `:"thread.run.completed"` + - `:failed` - - `class ThreadRunIncomplete` + - `type: :web_search_call` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + The type of the web search tool call. Always `web_search_call`. - - `data: Run` + - `:web_search_call` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent: Agent{ agent_name}` - - `event: :"thread.run.incomplete"` + The agent that produced this item. - - `:"thread.run.incomplete"` + - `agent_name: String` - - `class ThreadRunFailed` + The canonical name of the agent that produced this item. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `class BetaResponseFunctionToolCall` - - `data: Run` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `arguments: String` - - `event: :"thread.run.failed"` + A JSON string of the arguments to pass to the function. - - `:"thread.run.failed"` + - `call_id: String` - - `class ThreadRunCancelling` + 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) moves to a `cancelling` status. + - `name: String` - - `data: Run` + The name of the function to run. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: :function_call` - - `event: :"thread.run.cancelling"` + The type of the function tool call. Always `function_call`. - - `:"thread.run.cancelling"` + - `:function_call` - - `class ThreadRunCancelled` + - `id: String` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + The unique ID of the function tool call. - - `data: Run` + - `agent: Agent{ agent_name}` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The agent that produced this item. - - `event: :"thread.run.cancelled"` + - `agent_name: String` - - `:"thread.run.cancelled"` + The canonical name of the agent that produced this item. - - `class ThreadRunExpired` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + The execution context that produced this tool call. - - `data: Run` + - `class Direct` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: :direct` - - `event: :"thread.run.expired"` + - `:direct` - - `:"thread.run.expired"` + - `class Program` -### Thread Stream Event + - `caller_id: String` -- `class ThreadStreamEvent` + The call ID of the program item that produced this tool call. - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + - `type: :program` - - `data: Thread` + - `:program` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `namespace: String` - - `id: String` + The namespace of the function to run. - The identifier, which can be referenced in API endpoints. + - `status: :in_progress | :completed | :incomplete` - - `created_at: Integer` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The Unix timestamp (in seconds) for when the thread was created. + - `:in_progress` - - `metadata: 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. + - `class FunctionCallOutput` - - `object: :thread` + The output of a function tool call. - The object type, which is always `thread`. + - `call_id: String` - - `:thread` + The unique ID of the function tool call generated by the model. - - `tool_resources: ToolResources{ code_interpreter, file_search}` + - `output: String | BetaResponseFunctionCallOutputItemList` - 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, image, or file output of the function tool call. - - `code_interpreter: CodeInterpreter{ file_ids}` + - `String = String` - - `file_ids: Array[String]` + A JSON string of the output of the function tool 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. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `file_search: FileSearch{ vector_store_ids}` + An array of content outputs (text, image, file) for the function tool call. - - `vector_store_ids: Array[String]` + - `class BetaResponseInputTextContent` - 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 text input to the model. - - `event: :"thread.created"` + - `text: String` - - `:"thread.created"` + The text input to the model. - - `enabled: bool` + - `type: :input_text` - Whether to enable input audio transcription. + The type of the input item. Always `input_text`. -# Threads + - `:input_text` -## Create thread + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` -`beta.threads.create(**kwargs) -> 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`. -### Parameters + - `:explicit` -- `messages: Array[Message{ content, role, attachments, metadata}]` + - `class BetaResponseInputImageContent` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `content: String | Array[MessageContentPartParam]` + - `type: :input_image` - The text contents of the message. + The type of the input item. Always `input_image`. - - `String = String` + - `:input_image` - The text contents of the message. + - `detail: :low | :high | :auto | :original` - - `ArrayOfContentParts = Array[MessageContentPartParam]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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). + - `:low` - - `class ImageFileContentBlock` + - `:high` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `:auto` - - `image_file: ImageFile` + - `:original` - `file_id: 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. - - - `detail: :auto | :low | :high` + The ID of the file to be sent to the model. - 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`. + - `image_url: 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. - - `:low` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `type: :image_file` + - `mode: :explicit` - Always `image_file`. + The breakpoint mode. Always `explicit`. - - `:image_file` + - `:explicit` - - `class ImageURLContentBlock` + - `class BetaResponseInputFileContent` - References an image URL in the content of a message. + A file input to the model. - - `image_url: ImageURL` + - `type: :input_file` - - `url: String` + The type of the input item. Always `input_file`. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `:input_file` - `detail: :auto | :low | :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` + 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` @@ -6357,7705 +6007,18997 @@ Create thread - `:high` - - `type: :image_url` + - `file_data: String` - The type of the content part. + The base64-encoded data of the file to be sent to the model. - - `:image_url` + - `file_id: String` - - `class TextContentBlockParam` + The ID of the file to be sent to the model. - The text content that is part of a message. + - `file_url: String` - - `text: String` + The URL of the file to be sent to the model. - Text content to be sent to the model + - `filename: String` - - `type: :text` + The name of the file to be sent to the model. - Always `text`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:text` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `role: :user | :assistant` + - `mode: :explicit` - The role of the entity that is creating the message. Allowed values include: + The breakpoint mode. Always `explicit`. - - `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. + - `:explicit` - - `:user` + - `type: :function_call_output` - - `:assistant` + The type of the function tool call output. Always `function_call_output`. - - `attachments: Array[Attachment{ file_id, tools}]` + - `:function_call_output` - A list of files attached to the message, and the tools they should be added to. + - `id: String` - - `file_id: String` + The unique ID of the function tool call output. Populated when this item is returned via API. - The ID of the file to attach to the message. + - `agent: Agent{ agent_name}` - - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` + The agent that produced this item. - The tools to add this file to. + - `agent_name: String` - - `class CodeInterpreterTool` + The canonical name of the agent that produced this item. - - `type: :code_interpreter` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The type of tool being defined: `code_interpreter` + The execution context that produced this tool call. - - `:code_interpreter` + - `class Direct` - - `class FileSearch` + - `type: :direct` - - `type: :file_search` + The caller type. Always `direct`. - The type of tool being defined: `file_search` + - `:direct` - - `:file_search` + - `class Program` - - `metadata: Metadata` + - `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` -- `metadata: Metadata` + The caller type. Always `program`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:program` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `status: :in_progress | :completed | :incomplete` -- `tool_resources: ToolResources{ code_interpreter, file_search}` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - 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. + - `:in_progress` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `:completed` - - `file_ids: Array[String]` + - `:incomplete` - 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. + - `class AgentMessage` - - `file_search: FileSearch{ vector_store_ids, vector_stores}` + A message routed between agents. - - `vector_store_ids: Array[String]` + - `author: 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 sending agent identity. - - `vector_stores: Array[VectorStore{ chunking_strategy, file_ids, metadata}]` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - 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. + Plaintext, image, or encrypted content sent between agents. - - `chunking_strategy: Auto{ type} | Static{ static, type}` + - `class BetaResponseInputTextContent` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + A text input to the model. - - `class Auto` + - `class BetaResponseInputImageContent` - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `type: :auto` + - `class EncryptedContent` - Always `auto`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `:auto` + - `encrypted_content: String` - - `class Static` + Opaque encrypted content. - - `static: Static{ chunk_overlap_tokens, max_chunk_size_tokens}` + - `type: :encrypted_content` - - `chunk_overlap_tokens: Integer` + The type of the input item. Always `encrypted_content`. - The number of tokens that overlap between chunks. The default value is `400`. + - `:encrypted_content` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `recipient: String` - - `max_chunk_size_tokens: Integer` + The destination agent identity. - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + - `type: :agent_message` - - `type: :static` + The item type. Always `agent_message`. - Always `static`. + - `:agent_message` - - `:static` + - `id: String` - - `file_ids: Array[String]` + The unique ID of this agent message item. - 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. + - `agent: Agent{ agent_name}` - - `metadata: Metadata` + The agent that produced this 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. + - `agent_name: String` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The canonical name of the agent that produced this item. -### Returns + - `class MultiAgentCall` -- `class Thread` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The multi-agent action that was executed. - - `id: String` + - `:spawn_agent` - The identifier, which can be referenced in API endpoints. + - `:interrupt_agent` - - `created_at: Integer` + - `:list_agents` - The Unix timestamp (in seconds) for when the thread was created. + - `:send_message` - - `metadata: Metadata` + - `:followup_task` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:wait_agent` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `arguments: String` - - `object: :thread` + The action arguments as a JSON string. - The object type, which is always `thread`. + - `call_id: String` - - `:thread` + The unique ID linking this call to its output. - - `tool_resources: ToolResources{ code_interpreter, file_search}` + - `type: :multi_agent_call` - 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 item type. Always `multi_agent_call`. - - `code_interpreter: CodeInterpreter{ file_ids}` + - `:multi_agent_call` - - `file_ids: Array[String]` + - `id: 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. + The unique ID of this multi-agent call. - - `file_search: FileSearch{ vector_store_ids}` + - `agent: Agent{ agent_name}` - - `vector_store_ids: Array[String]` + The agent that produced this item. - 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. + - `agent_name: String` -### Example + The canonical name of the agent that produced this item. -```ruby -require "openai" + - `class MultiAgentCallOutput` -openai = OpenAI::Client.new(api_key: "My API Key") + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` -thread = openai.beta.threads.create + The multi-agent action that produced this result. -puts(thread) -``` + - `:spawn_agent` -#### Response + - `:interrupt_agent` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `:list_agents` -## Create thread and run + - `:send_message` -`beta.threads.create_and_run(**kwargs) -> Run` + - `:followup_task` -**post** `/threads/runs` + - `:wait_agent` -Create thread and run + - `call_id: String` -### Parameters + The unique ID of the multi-agent call. -- `assistant_id: String` + - `output: Array[Output{ text, type, annotations}]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + Text output returned by the multi-agent action. -- `instructions: String` + - `text: String` - Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. + The text content. -- `max_completion_tokens: Integer` + - `type: :output_text` - 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 content type. Always `output_text`. -- `max_prompt_tokens: Integer` + - `:output_text` - 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. + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` -- `metadata: 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. + - `UnionMember0 = Array[UnionMember0{ 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` -- `model: String | ChatModel` + The ID of the file. - 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. + - `filename: String` - - `String = String` + The filename of the file cited. - - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + - `index: Integer` - - `:"gpt-5.6-sol"` + The index of the file in the list of files. - - `:"gpt-5.6-terra"` + - `type: :file_citation` - - `:"gpt-5.6-luna"` + The citation type. Always `file_citation`. - - `:"gpt-5.4"` + - `:file_citation` - - `:"gpt-5.4-mini"` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `:"gpt-5.4-nano"` + - `end_index: Integer` - - `:"gpt-5.4-mini-2026-03-17"` + The index of the last character of the citation in the message. - - `:"gpt-5.4-nano-2026-03-17"` + - `start_index: Integer` - - `:"gpt-5.3-chat-latest"` + The index of the first character of the citation in the message. - - `:"gpt-5.2"` + - `title: String` - - `:"gpt-5.2-2025-12-11"` + The title of the cited resource. - - `:"gpt-5.2-chat-latest"` + - `type: :url_citation` - - `:"gpt-5.2-pro"` + The citation type. Always `url_citation`. - - `:"gpt-5.2-pro-2025-12-11"` + - `:url_citation` - - `:"gpt-5.1"` + - `url: String` - - `:"gpt-5.1-2025-11-13"` + The URL of the cited resource. - - `:"gpt-5.1-codex"` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `:"gpt-5.1-mini"` + - `container_id: String` - - `:"gpt-5.1-chat-latest"` + The ID of the container. - - `:"gpt-5"` + - `end_index: Integer` - - `:"gpt-5-mini"` + The index of the last character of the citation in the message. - - `:"gpt-5-nano"` + - `file_id: String` - - `:"gpt-5-2025-08-07"` + The ID of the container file. - - `:"gpt-5-mini-2025-08-07"` + - `filename: String` - - `:"gpt-5-nano-2025-08-07"` + The filename of the container file cited. - - `:"gpt-5-chat-latest"` + - `start_index: Integer` - - `:"gpt-4.1"` + The index of the first character of the citation in the message. - - `:"gpt-4.1-mini"` + - `type: :container_file_citation` - - `:"gpt-4.1-nano"` + The citation type. Always `container_file_citation`. - - `:"gpt-4.1-2025-04-14"` + - `:container_file_citation` - - `:"gpt-4.1-mini-2025-04-14"` + - `type: :multi_agent_call_output` - - `:"gpt-4.1-nano-2025-04-14"` + The item type. Always `multi_agent_call_output`. - - `:"o4-mini"` + - `:multi_agent_call_output` - - `:"o4-mini-2025-04-16"` + - `id: String` - - `:o3` + The unique ID of this multi-agent call output. - - `:"o3-2025-04-16"` + - `agent: Agent{ 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"` + - `class ToolSearchCall` - - `:"o1-preview"` + - `arguments: untyped` - - `:"o1-preview-2024-09-12"` + The arguments supplied to the tool search call. - - `:"o1-mini"` + - `type: :tool_search_call` - - `:"o1-mini-2024-09-12"` + The item type. Always `tool_search_call`. - - `:"gpt-4o"` + - `:tool_search_call` - - `:"gpt-4o-2024-11-20"` + - `id: String` - - `:"gpt-4o-2024-08-06"` + The unique ID of this tool search call. - - `:"gpt-4o-2024-05-13"` + - `agent: Agent{ agent_name}` - - `:"gpt-4o-audio-preview"` + The agent that produced this item. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `agent_name: String` - - `:"gpt-4o-audio-preview-2024-12-17"` + The canonical name of the agent that produced this item. - - `:"gpt-4o-audio-preview-2025-06-03"` + - `call_id: String` - - `:"gpt-4o-mini-audio-preview"` + The unique ID of the tool search call generated by the model. - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `execution: :server | :client` - - `:"gpt-4o-search-preview"` + Whether tool search was executed by the server or by the client. - - `:"gpt-4o-mini-search-preview"` + - `:server` - - `:"gpt-4o-search-preview-2025-03-11"` + - `:client` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `status: :in_progress | :completed | :incomplete` - - `:"chatgpt-4o-latest"` + The status of the tool search call. - - `:"codex-mini-latest"` + - `:in_progress` - - `:"gpt-4o-mini"` + - `:completed` - - `:"gpt-4o-mini-2024-07-18"` + - `:incomplete` - - `:"gpt-4-turbo"` + - `class BetaResponseToolSearchOutputItemParam` - - `:"gpt-4-turbo-2024-04-09"` + - `tools: Array[BetaTool]` - - `:"gpt-4-0125-preview"` + The loaded tool definitions returned by the tool search output. - - `:"gpt-4-turbo-preview"` + - `class BetaFunctionTool` - - `:"gpt-4-1106-preview"` + 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-4-vision-preview"` + - `name: String` - - `:"gpt-4"` + The name of the function to call. - - `:"gpt-4-0314"` + - `parameters: Hash[Symbol, untyped]` - - `:"gpt-4-0613"` + A JSON schema object describing the parameters of the function. - - `:"gpt-4-32k"` + - `strict: bool` - - `:"gpt-4-32k-0314"` + Whether strict parameter validation is enforced for this function tool. - - `:"gpt-4-32k-0613"` + - `type: :function` - - `:"gpt-3.5-turbo"` + The type of the function tool. Always `function`. - - `:"gpt-3.5-turbo-16k"` + - `:function` - - `:"gpt-3.5-turbo-0301"` + - `allowed_callers: Array[:direct | :programmatic]` - - `:"gpt-3.5-turbo-0613"` + The tool invocation context(s). - - `:"gpt-3.5-turbo-1106"` + - `:direct` - - `:"gpt-3.5-turbo-0125"` + - `:programmatic` - - `:"gpt-3.5-turbo-16k-0613"` + - `defer_loading: bool` -- `parallel_tool_calls: bool` + Whether this function is deferred and loaded via tool search. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `description: String` -- `response_format: AssistantResponseFormatOption` + A description of the function. Used by the model to determine whether or not to call the function. - 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`. + - `output_schema: Hash[Symbol, untyped]` - 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). + A JSON schema object describing the JSON value encoded in string outputs for this function. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class BetaFileSearchTool` - **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 searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `AssistantResponseFormatOption = :auto` + - `type: :file_search` - `auto` is the default value + The type of the file search tool. Always `file_search`. - - `:auto` + - `:file_search` - - `class ResponseFormatText` + - `vector_store_ids: Array[String]` - Default response format. Used to generate text responses. + The IDs of the vector stores to search. - - `type: :text` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - The type of response format being defined. Always `text`. + A filter to apply. - - `:text` + - `class ComparisonFilter` - - `class ResponseFormatJSONObject` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - 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. + - `key: String` - - `type: :json_object` + The key to compare against the value. - The type of response format being defined. Always `json_object`. + - `type: :eq | :ne | :gt | 5 more` - - `:json_object` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `class ResponseFormatJSONSchema` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:eq` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `:ne` - Structured Outputs configuration options, including a JSON Schema. + - `:gt` - - `name: String` + - `:gte` - 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. + - `:lt` - - `description: String` + - `:lte` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:in` - - `schema: Hash[Symbol, untyped]` + - `:nin` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `value: String | Float | bool | Array[String | Float]` - - `strict: bool` + The value to compare against the attribute key; supports string, number, or boolean types. - 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). + - `String = String` - - `type: :json_schema` + - `Float = Float` - The type of response format being defined. Always `json_schema`. + - `UnionMember2 = bool` - - `:json_schema` + - `UnionMember3 = Array[String | Float]` -- `stream: bool` + - `String = String` - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + - `Float = Float` -- `temperature: Float` + - `class CompoundFilter` - 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. + Combine multiple filters using `and` or `or`. -- `thread: Thread{ messages, metadata, tool_resources}` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - Options to create a new thread. If no thread is provided when running a - request, an empty thread will be created. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `messages: Array[Message{ content, role, attachments, metadata}]` + - `class ComparisonFilter` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `content: String | Array[MessageContentPartParam]` + - `key: String` - The text contents of the message. + The key to compare against the value. - - `String = String` + - `type: :eq | :ne | :gt | 5 more` - The text contents of the message. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `ArrayOfContentParts = Array[MessageContentPartParam]` + - `eq`: equals + - `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 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). + - `:eq` - - `class ImageFileContentBlock` + - `:ne` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `:gt` - - `image_file: ImageFile` + - `:gte` - - `file_id: String` + - `:lt` - 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. + - `:lte` - - `detail: :auto | :low | :high` + - `:in` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `:nin` - - `:auto` + - `value: String | Float | bool | Array[String | Float]` - - `:low` + The value to compare against the attribute key; supports string, number, or boolean types. - - `:high` + - `String = String` - - `type: :image_file` + - `Float = Float` - Always `image_file`. + - `UnionMember2 = bool` - - `:image_file` + - `UnionMember3 = Array[String | Float]` - - `class ImageURLContentBlock` + - `String = String` - References an image URL in the content of a message. + - `Float = Float` - - `image_url: ImageURL` + - `UnionMember1 = untyped` - - `url: String` + - `type: :and | :or` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Type of operation: `and` or `or`. - - `detail: :auto | :low | :high` + - `:and` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `:or` - - `:auto` + - `max_num_results: Integer` - - `:low` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `:high` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - - `type: :image_url` + Ranking options for search. - The type of the content part. + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `:image_url` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `class TextContentBlockParam` + - `embedding_weight: Float` - The text content that is part of a message. + The weight of the embedding in the reciprocal ranking fusion. - - `text: String` + - `text_weight: Float` - Text content to be sent to the model + The weight of the text in the reciprocal ranking fusion. - - `type: :text` + - `ranker: :auto | :"default-2024-11-15"` - Always `text`. + The ranker to use for the file search. - - `:text` + - `:auto` - - `role: :user | :assistant` + - `:"default-2024-11-15"` - The role of the entity that is creating the message. Allowed values include: + - `score_threshold: Float` - - `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 score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `:user` + - `class BetaComputerTool` - - `:assistant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `attachments: Array[Attachment{ file_id, tools}]` + - `type: :computer` - A list of files attached to the message, and the tools they should be added to. + The type of the computer tool. Always `computer`. - - `file_id: String` + - `:computer` - The ID of the file to attach to the message. + - `class BetaComputerUsePreviewTool` - - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The tools to add this file to. + - `display_height: Integer` - - `class CodeInterpreterTool` + The height of the computer display. - - `type: :code_interpreter` + - `display_width: Integer` - The type of tool being defined: `code_interpreter` + The width of the computer display. - - `:code_interpreter` + - `environment: :windows | :mac | :linux | 2 more` - - `class FileSearch` + The type of computer environment to control. - - `type: :file_search` + - `:windows` - The type of tool being defined: `file_search` + - `:mac` - - `:file_search` + - `:linux` - - `metadata: Metadata` + - `:ubuntu` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:browser` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: :computer_use_preview` - - `metadata: Metadata` + The type of the computer use tool. Always `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. + - `:computer_use_preview` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class BetaWebSearchTool` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + 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 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: :web_search | :web_search_2025_08_26` - - `code_interpreter: CodeInterpreter{ file_ids}` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `file_ids: Array[String]` + - `:web_search` - 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. + - `:web_search_2025_08_26` - - `file_search: FileSearch{ vector_store_ids, vector_stores}` + - `filters: Filters{ allowed_domains}` - - `vector_store_ids: Array[String]` + Filters for the search. - 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_domains: Array[String]` - - `vector_stores: Array[VectorStore{ chunking_strategy, file_ids, metadata}]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - 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. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `chunking_strategy: Auto{ type} | Static{ static, type}` + - `search_context_size: :low | :medium | :high` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class Auto` + - `:low` - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `:medium` - - `type: :auto` + - `:high` - Always `auto`. + - `user_location: UserLocation{ city, country, region, 2 more}` - - `:auto` + The approximate location of the user. - - `class Static` + - `city: String` - - `static: Static{ chunk_overlap_tokens, max_chunk_size_tokens}` + Free text input for the city of the user, e.g. `San Francisco`. - - `chunk_overlap_tokens: Integer` + - `country: String` - The number of tokens that overlap between chunks. The default value is `400`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `region: String` - - `max_chunk_size_tokens: Integer` + Free text input for the region of the user, e.g. `California`. - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + - `timezone: String` - - `type: :static` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Always `static`. + - `type: :approximate` - - `:static` + The type of location approximation. Always `approximate`. - - `file_ids: Array[String]` + - `:approximate` - 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. + - `class Mcp` - - `metadata: Metadata` + 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). - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `server_label: String` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A label for this MCP server, used to identify it in tool calls. -- `tool_choice: AssistantToolChoiceOption` + - `type: :mcp` - 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 MCP tool. Always `mcp`. - - `Auto = :none | :auto | :required` + - `:mcp` - `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. + - `allowed_callers: Array[:direct | :programmatic]` - - `:none` + The tool invocation context(s). - - `:auto` + - `:direct` - - `:required` + - `:programmatic` - - `class AssistantToolChoice` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - Specifies a tool the model should use. Use to force the model to call a specific tool. + List of allowed tool names or a filter object. - - `type: :function | :code_interpreter | :file_search` + - `McpAllowedTools = Array[String]` - The type of the tool. If type is `function`, the function name must be set + A string array of allowed tool names - - `:function` + - `class McpToolFilter` - - `:code_interpreter` + A filter object to specify which tools are allowed. - - `:file_search` + - `read_only: bool` - - `function: AssistantToolChoiceFunction` + Indicates whether or not a tool modifies data or is read-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: Array[String]` - The name of the function to call. + List of allowed tool names. -- `tool_resources: ToolResources{ code_interpreter, file_search}` + - `authorization: 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. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `code_interpreter: CodeInterpreter{ file_ids}` + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `file_ids: Array[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 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. + Currently supported `connector_id` values are: - - `file_search: FileSearch{ vector_store_ids}` + - 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` - - `vector_store_ids: Array[String]` + - `:connector_dropbox` - 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. + - `:connector_gmail` -- `tools: Array[untyped]` + - `:connector_googlecalendar` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + - `:connector_googledrive` -- `top_p: Float` + - `:connector_microsoftteams` - 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. + - `:connector_outlookcalendar` - We generally recommend altering this or temperature but not both. + - `:connector_outlookemail` -- `truncation_strategy: TruncationStrategy{ type, last_messages}` + - `:connector_sharepoint` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `defer_loading: bool` - - `type: :auto | :last_messages` + Whether this MCP tool is deferred and discovered via tool search. - 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`. + - `headers: Hash[Symbol, String]` - - `:auto` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `:last_messages` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `last_messages: Integer` + Specify which of the MCP server's tools require approval. - The number of most recent messages from the thread when constructing the context for the run. + - `class McpToolApprovalFilter` -### Returns + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. -- `class Run` + - `always: Always{ read_only, tool_names}` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A filter object to specify which tools are allowed. - - `id: String` + - `read_only: bool` - The identifier, which can be referenced in API endpoints. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `assistant_id: String` + - `tool_names: Array[String]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + List of allowed tool names. - - `cancelled_at: Integer` + - `never: Never{ read_only, tool_names}` - The Unix timestamp (in seconds) for when the run was cancelled. + A filter object to specify which tools are allowed. - - `completed_at: Integer` + - `read_only: bool` - The Unix timestamp (in seconds) for when the run was 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. - - `created_at: Integer` + - `tool_names: Array[String]` - The Unix timestamp (in seconds) for when the run was created. + List of allowed tool names. - - `expires_at: Integer` + - `McpToolApprovalSetting = :always | :never` - The Unix timestamp (in seconds) for when the run will expire. + 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. - - `failed_at: Integer` + - `:always` - The Unix timestamp (in seconds) for when the run failed. + - `:never` - - `incomplete_details: IncompleteDetails{ reason}` + - `server_description: String` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + Optional description of the MCP server, used to provide more context. - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `server_url: 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 URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:max_completion_tokens` + - `tunnel_id: String` - - `:max_prompt_tokens` + 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. - - `instructions: String` + - `class CodeInterpreter` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A tool that runs Python code to help generate a response to a prompt. - - `last_error: LastError{ code, message}` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - The last error associated with this run. Will be `null` if there are no errors. + 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: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `String = String` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The container ID. - - `:server_error` + - `class CodeInterpreterToolAuto` - - `:rate_limit_exceeded` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `:invalid_prompt` + - `type: :auto` - - `message: String` + Always `auto`. - A human-readable description of the error. + - `:auto` - - `max_completion_tokens: Integer` + - `file_ids: Array[String]` - The maximum number of completion tokens specified to have been used over the course of the run. + An optional list of uploaded files to make available to your code. - - `max_prompt_tokens: Integer` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The maximum number of prompt tokens specified to have been used over the course of the run. + The memory limit for the code interpreter container. - - `metadata: Metadata` + - `:"1g"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:"4g"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:"16g"` - - `model: String` + - `:"64g"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `object: :"thread.run"` + Network access policy for the container. - The object type, which is always `thread.run`. + - `class BetaContainerNetworkPolicyDisabled` - - `:"thread.run"` + - `type: :disabled` - - `parallel_tool_calls: bool` + Disable outbound network access. Always `disabled`. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `:disabled` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + - `class BetaContainerNetworkPolicyAllowlist` - Details on the action required to continue the run. Will be `null` if no action is required. + - `allowed_domains: Array[String]` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + A list of allowed domains when type is `allowlist`. - Details on the tool outputs needed for this run to continue. + - `type: :allowlist` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + Allow outbound network access only to specified domains. Always `allowlist`. - A list of the relevant tool calls. + - `:allowlist` - - `id: String` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - 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. + Optional domain-scoped secrets for allowlisted domains. - - `function: Function{ arguments, name}` + - `domain: String` - The function definition. + The domain associated with the secret. - - `arguments: String` + - `name: String` - The arguments that the model expects you to pass to the function. + The name of the secret to inject for the domain. - - `name: String` + - `value: String` - The name of the function. + The secret value to inject for the domain. - - `type: :function` + - `type: :code_interpreter` - The type of tool call the output is required for. For now, this is always `function`. + The type of the code interpreter tool. Always `code_interpreter`. - - `:function` + - `:code_interpreter` - - `type: :submit_tool_outputs` + - `allowed_callers: Array[:direct | :programmatic]` - For now, this is always `submit_tool_outputs`. + The tool invocation context(s). - - `:submit_tool_outputs` + - `:direct` - - `response_format: AssistantResponseFormatOption` + - `: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`. + - `class ProgrammaticToolCalling` - 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: :programmatic_tool_calling` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The type of the tool. Always `programmatic_tool_calling`. - **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_tool_calling` - - `AssistantResponseFormatOption = :auto` + - `class ImageGeneration` - `auto` is the default value + A tool that generates images using the GPT image models. - - `:auto` + - `type: :image_generation` - - `class ResponseFormatText` + The type of the image generation tool. Always `image_generation`. - Default response format. Used to generate text responses. + - `:image_generation` - - `type: :text` + - `action: :generate | :edit | :auto` - The type of response format being defined. Always `text`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `:text` + - `:generate` - - `class ResponseFormatJSONObject` + - `:edit` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `:auto` - - `type: :json_object` + - `background: :transparent | :opaque | :auto` - The type of response format being defined. Always `json_object`. + 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. - - `:json_object` + `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. - - `class ResponseFormatJSONSchema` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:transparent` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `:opaque` - Structured Outputs configuration options, including a JSON Schema. + - `:auto` - - `name: String` + - `input_fidelity: :high | :low` - 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. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `description: String` + - `:high` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:low` - - `schema: Hash[Symbol, untyped]` + - `input_image_mask: InputImageMask{ file_id, image_url}` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `strict: bool` + - `file_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). + File ID for the mask image. - - `type: :json_schema` + - `image_url: String` - The type of response format being defined. Always `json_schema`. + Base64-encoded mask image. - - `:json_schema` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `started_at: Integer` + The image generation model to use. Default: `gpt-image-1`. - The Unix timestamp (in seconds) for when the run was started. + - `String = String` - - `status: untyped` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `thread_id: String` + The image generation model to use. Default: `gpt-image-1`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `:"gpt-image-1"` - - `tool_choice: AssistantToolChoiceOption` + - `:"gpt-image-1-mini"` - 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. + - `:"gpt-image-2"` - - `Auto = :none | :auto | :required` + - `:"gpt-image-2-2026-04-21"` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `:"gpt-image-1.5"` - - `:none` + - `:"chatgpt-image-latest"` - - `:auto` + - `moderation: :auto | :low` - - `:required` + Moderation level for the generated image. Default: `auto`. - - `class AssistantToolChoice` + - `:auto` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `:low` - - `type: :function | :code_interpreter | :file_search` + - `output_compression: Integer` - The type of the tool. If type is `function`, the function name must be set + Compression level for the output image. Default: 100. - - `:function` + - `output_format: :png | :webp | :jpeg` - - `:code_interpreter` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `:file_search` + - `:png` - - `function: AssistantToolChoiceFunction` + - `:webp` - - `name: String` + - `:jpeg` - The name of the function to call. + - `partial_images: Integer` - - `tools: Array[untyped]` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `quality: :low | :medium | :high | :auto` - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `:low` - - `type: :auto | :last_messages` + - `:medium` - 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`. + - `:high` - `:auto` - - `:last_messages` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `last_messages: Integer` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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 number of most recent messages from the thread when constructing the context for the run. + - `String = String` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - 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 size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `completion_tokens: Integer` + - `:"1024x1024"` - Number of completion tokens used over the course of the run. + - `:"1024x1536"` - - `prompt_tokens: Integer` + - `:"1536x1024"` - Number of prompt tokens used over the course of the run. + - `:auto` - - `total_tokens: Integer` + - `class LocalShell` - Total number of tokens used (prompt + completion). + A tool that allows the model to execute shell commands in a local environment. - - `temperature: Float` + - `type: :local_shell` - The sampling temperature used for this run. If not set, defaults to 1. + The type of the local shell tool. Always `local_shell`. - - `top_p: Float` + - `:local_shell` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `class BetaFunctionShellTool` -### Example + A tool that allows the model to execute shell commands. -```ruby -require "openai" + - `type: :shell` -openai = OpenAI::Client.new(api_key: "My API Key") + The type of the shell tool. Always `shell`. -run = openai.beta.threads.create_and_run(assistant_id: "assistant_id") + - `:shell` -puts(run) -``` + - `allowed_callers: Array[:direct | :programmatic]` -#### Response + The tool invocation context(s). -```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": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `:direct` -## Retrieve thread + - `:programmatic` -`beta.threads.retrieve(thread_id) -> Thread` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` -**get** `/threads/{thread_id}` + - `class BetaContainerAuto` -Retrieve thread + - `type: :container_auto` -### Parameters + Automatically creates a container for this request -- `thread_id: String` + - `:container_auto` -### Returns + - `file_ids: Array[String]` -- `class Thread` + An optional list of uploaded files to make available to your code. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `id: String` + The memory limit for the container. - The identifier, which can be referenced in API endpoints. + - `:"1g"` - - `created_at: Integer` + - `:"4g"` - The Unix timestamp (in seconds) for when the thread was created. + - `:"16g"` - - `metadata: Metadata` + - `:"64g"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Network access policy for the container. - - `object: :thread` + - `class BetaContainerNetworkPolicyDisabled` - The object type, which is always `thread`. + - `class BetaContainerNetworkPolicyAllowlist` - - `:thread` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + An optional list of skills referenced by id or inline data. - 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. + - `class BetaSkillReference` - - `code_interpreter: CodeInterpreter{ file_ids}` + - `skill_id: String` - - `file_ids: Array[String]` + The ID of the referenced skill. - 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: :skill_reference` - - `file_search: FileSearch{ vector_store_ids}` + References a skill created with the /v1/skills endpoint. - - `vector_store_ids: Array[String]` + - `:skill_reference` - 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. + - `version: String` -### Example + Optional skill version. Use a positive integer or 'latest'. Omit for default. -```ruby -require "openai" + - `class BetaInlineSkill` -openai = OpenAI::Client.new(api_key: "My API Key") + - `description: String` -thread = openai.beta.threads.retrieve("thread_id") + The description of the skill. -puts(thread) -``` + - `name: String` -#### Response + The name of the skill. -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `source: BetaInlineSkillSource` -## Modify thread + Inline skill payload -`beta.threads.update(thread_id, **kwargs) -> Thread` + - `data: String` -**post** `/threads/{thread_id}` + Base64-encoded skill zip bundle. -Modify thread + - `media_type: :"application/zip"` -### Parameters + The media type of the inline skill payload. Must be `application/zip`. -- `thread_id: String` + - `:"application/zip"` -- `metadata: Metadata` + - `type: :base64` - Set of 16 key-value pairs that can be attached to an object. 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 inline skill source. Must be `base64`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:base64` -- `tool_resources: ToolResources{ code_interpreter, file_search}` + - `type: :inline` - 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. + Defines an inline skill for this request. - - `code_interpreter: CodeInterpreter{ file_ids}` + - `:inline` - - `file_ids: Array[String]` + - `class BetaLocalEnvironment` - 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: :local` - - `file_search: FileSearch{ vector_store_ids}` + Use a local computer environment. - - `vector_store_ids: Array[String]` + - `:local` - 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. + - `skills: Array[BetaLocalSkill]` -### Returns + An optional list of skills. -- `class Thread` + - `description: String` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The description of the skill. - - `id: String` + - `name: String` - The identifier, which can be referenced in API endpoints. + The name of the skill. - - `created_at: Integer` + - `path: String` - The Unix timestamp (in seconds) for when the thread was created. + The path to the directory containing the skill. - - `metadata: Metadata` + - `class BetaContainerReference` - Set of 16 key-value pairs that can be attached to an object. 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 referenced container. - - `object: :thread` + - `type: :container_reference` - The object type, which is always `thread`. + References a container created with the /v1/containers endpoint - - `:thread` + - `:container_reference` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + - `class BetaCustomTool` - 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 custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `code_interpreter: CodeInterpreter{ file_ids}` + - `name: String` - - `file_ids: Array[String]` + The name of the custom tool, used to identify it in tool calls. - 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: :custom` - - `file_search: FileSearch{ vector_store_ids}` + The type of the custom tool. Always `custom`. - - `vector_store_ids: Array[String]` + - `:custom` - 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: Array[:direct | :programmatic]` -### Example + The tool invocation context(s). -```ruby -require "openai" + - `:direct` -openai = OpenAI::Client.new(api_key: "My API Key") + - `:programmatic` -thread = openai.beta.threads.update("thread_id") + - `defer_loading: bool` -puts(thread) -``` + Whether this tool should be deferred and discovered via tool search. -#### Response + - `description: 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" - ] - } - } -} -``` + Optional description of the custom tool, used to provide more context. -## Delete thread + - `format_: Text{ type} | Grammar{ definition, syntax, type}` -`beta.threads.delete(thread_id) -> ThreadDeleted` + The input format for the custom tool. Default is unconstrained text. -**delete** `/threads/{thread_id}` + - `class Text` -Delete thread + Unconstrained free-form text. -### Parameters + - `type: :text` -- `thread_id: String` + Unconstrained text format. Always `text`. -### Returns + - `:text` -- `class ThreadDeleted` + - `class Grammar` - - `id: String` + A grammar defined by the user. - - `deleted: bool` + - `definition: String` - - `object: :"thread.deleted"` + The grammar definition. - - `:"thread.deleted"` + - `syntax: :lark | :regex` -### Example + The syntax of the grammar definition. One of `lark` or `regex`. -```ruby -require "openai" + - `:lark` -openai = OpenAI::Client.new(api_key: "My API Key") + - `:regex` -thread_deleted = openai.beta.threads.delete("thread_id") + - `type: :grammar` -puts(thread_deleted) -``` + Grammar format. Always `grammar`. -#### Response + - `:grammar` -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` + - `class BetaNamespaceTool` -## Domain Types + Groups function/custom tools under a shared namespace. -### Assistant Response Format Option + - `description: String` -- `AssistantResponseFormatOption = :auto | ResponseFormatText | ResponseFormatJSONObject | ResponseFormatJSONSchema` + A description of the namespace shown to the model. - 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`. + - `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 namespace name used in tool calls (for example, `crm`). - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - **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 function/custom tools available inside this namespace. - - `AssistantResponseFormatOption = :auto` + - `class Function` - `auto` is the default value + - `name: String` - - `:auto` + - `type: :function` - - `class ResponseFormatText` + - `:function` - Default response format. Used to generate text responses. + - `allowed_callers: Array[:direct | :programmatic]` - - `type: :text` + The tool invocation context(s). - The type of response format being defined. Always `text`. + - `:direct` - - `:text` + - `:programmatic` - - `class ResponseFormatJSONObject` + - `defer_loading: bool` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Whether this function should be deferred and discovered via tool search. - - `type: :json_object` + - `description: String` - The type of response format being defined. Always `json_object`. + - `output_schema: Hash[Symbol, untyped]` - - `:json_object` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class ResponseFormatJSONSchema` + - `parameters: untyped` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `strict: bool` - - `json_schema: JSONSchema{ name, description, schema, strict}` + 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. - Structured Outputs configuration options, including a JSON Schema. + - `class BetaCustomTool` - - `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 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: :namespace` - - `description: String` + The type of the tool. Always `namespace`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:namespace` - - `schema: Hash[Symbol, untyped]` + - `class BetaToolSearchTool` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Hosted or BYOT tool search configuration for deferred tools. - - `strict: bool` + - `type: :tool_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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the tool. Always `tool_search`. - - `type: :json_schema` + - `:tool_search` - The type of response format being defined. Always `json_schema`. + - `description: String` - - `:json_schema` + Description shown to the model for a client-executed tool search tool. -### Assistant Tool Choice + - `execution: :server | :client` -- `class AssistantToolChoice` + Whether tool search is executed by the server or by the client. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `:server` - - `type: :function | :code_interpreter | :file_search` + - `:client` - The type of the tool. If type is `function`, the function name must be set + - `parameters: untyped` - - `:function` + Parameter schema for a client-executed tool search tool. - - `:code_interpreter` + - `class BetaWebSearchPreviewTool` - - `:file_search` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `function: AssistantToolChoiceFunction` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `name: String` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The name of the function to call. + - `:web_search_preview` -### Assistant Tool Choice Function + - `:web_search_preview_2025_03_11` -- `class AssistantToolChoiceFunction` + - `search_content_types: Array[:text | :image]` - - `name: String` + - `:text` - The name of the function to call. + - `:image` -### Assistant Tool Choice Option + - `search_context_size: :low | :medium | :high` -- `AssistantToolChoiceOption = :none | :auto | :required | AssistantToolChoice` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - 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. + - `:low` - - `Auto = :none | :auto | :required` + - `:medium` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `:high` - - `:none` + - `user_location: UserLocation{ type, city, country, 2 more}` - - `:auto` + The user's location. - - `:required` + - `type: :approximate` - - `class AssistantToolChoice` + The type of location approximation. Always `approximate`. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `:approximate` - - `type: :function | :code_interpreter | :file_search` + - `city: String` - The type of the tool. If type is `function`, the function name must be set + Free text input for the city of the user, e.g. `San Francisco`. - - `:function` + - `country: String` - - `:code_interpreter` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `:file_search` + - `region: String` - - `function: AssistantToolChoiceFunction` + Free text input for the region of the user, e.g. `California`. - - `name: String` + - `timezone: 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`. -### Thread + - `class BetaApplyPatchTool` -- `class Thread` + Allows the assistant to create, delete, or update files using unified diffs. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `type: :apply_patch` - - `id: String` + The type of the tool. Always `apply_patch`. - The identifier, which can be referenced in API endpoints. + - `:apply_patch` - - `created_at: Integer` + - `allowed_callers: Array[:direct | :programmatic]` - The Unix timestamp (in seconds) for when the thread was created. + 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. + - `type: :tool_search_output` - - `object: :thread` + The item type. Always `tool_search_output`. - The object type, which is always `thread`. + - `:tool_search_output` - - `:thread` + - `id: String` - - `tool_resources: ToolResources{ code_interpreter, file_search}` + The unique ID of this 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. + - `agent: Agent{ agent_name}` - - `code_interpreter: CodeInterpreter{ file_ids}` + The agent that produced this item. - - `file_ids: Array[String]` + - `agent_name: 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. + The canonical name of the agent that produced this item. - - `file_search: FileSearch{ vector_store_ids}` + - `call_id: String` - - `vector_store_ids: Array[String]` + The unique ID of the tool search call generated by the model. - 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. + - `execution: :server | :client` -### Thread Deleted + Whether tool search was executed by the server or by the client. -- `class ThreadDeleted` + - `:server` - - `id: String` + - `:client` - - `deleted: bool` + - `status: :in_progress | :completed | :incomplete` - - `object: :"thread.deleted"` + The status of the tool search output. - - `:"thread.deleted"` + - `:in_progress` -# Runs + - `:completed` -## List runs + - `:incomplete` -`beta.threads.runs.list(thread_id, **kwargs) -> CursorPage` + - `class AdditionalTools` -**get** `/threads/{thread_id}/runs` + - `role: :developer` -List runs + The role that provided the additional tools. Only `developer` is supported. -### Parameters + - `:developer` -- `thread_id: String` + - `tools: Array[BetaTool]` -- `after: String` + A list of additional tools made available at this item. - 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. + - `class BetaFunctionTool` -- `before: 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). - 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. + - `class BetaFileSearchTool` -- `limit: Integer` + 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 limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `class BetaComputerTool` -- `order: :asc | :desc` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `class BetaComputerUsePreviewTool` - - `:asc` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:desc` + - `class BetaWebSearchTool` -### Returns + 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). -- `class Run` + - `class Mcp` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + 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` + - `class CodeInterpreter` - The identifier, which can be referenced in API endpoints. + A tool that runs Python code to help generate a response to a prompt. - - `assistant_id: String` + - `class ProgrammaticToolCalling` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `class ImageGeneration` - - `cancelled_at: Integer` + A tool that generates images using the GPT image models. - The Unix timestamp (in seconds) for when the run was cancelled. + - `class LocalShell` - - `completed_at: Integer` + A tool that allows the model to execute shell commands in a local environment. - The Unix timestamp (in seconds) for when the run was completed. + - `class BetaFunctionShellTool` - - `created_at: Integer` + A tool that allows the model to execute shell commands. - The Unix timestamp (in seconds) for when the run was created. + - `class BetaCustomTool` - - `expires_at: Integer` + 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 Unix timestamp (in seconds) for when the run will expire. + - `class BetaNamespaceTool` - - `failed_at: Integer` + Groups function/custom tools under a shared namespace. - The Unix timestamp (in seconds) for when the run failed. + - `class BetaToolSearchTool` - - `incomplete_details: IncompleteDetails{ reason}` + Hosted or BYOT tool search configuration for deferred tools. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `class BetaWebSearchPreviewTool` - - `reason: :max_completion_tokens | :max_prompt_tokens` + 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 reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `class BetaApplyPatchTool` - - `:max_completion_tokens` + Allows the assistant to create, delete, or update files using unified diffs. - - `:max_prompt_tokens` + - `type: :additional_tools` - - `instructions: String` + The item type. Always `additional_tools`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:additional_tools` - - `last_error: LastError{ code, message}` + - `id: String` - The last error associated with this run. Will be `null` if there are no errors. + The unique ID of this additional tools item. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `agent: Agent{ agent_name}` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The agent that produced this item. - - `:server_error` + - `agent_name: String` - - `:rate_limit_exceeded` + The canonical name of the agent that produced this item. - - `:invalid_prompt` + - `class BetaResponseReasoningItem` - - `message: 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). - A human-readable description of the error. + - `id: String` - - `max_completion_tokens: Integer` + The unique identifier of the reasoning content. - The maximum number of completion tokens specified to have been used over the course of the run. + - `summary: Array[Summary{ text, type}]` - - `max_prompt_tokens: Integer` + Reasoning summary content. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `text: String` - - `metadata: Metadata` + A summary of the reasoning output from the model so far. - Set of 16 key-value pairs that can be attached to an object. 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: :summary_text` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the object. Always `summary_text`. - - `model: String` + - `:summary_text` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: :reasoning` - - `object: :"thread.run"` + The type of the object. Always `reasoning`. - The object type, which is always `thread.run`. + - `:reasoning` - - `:"thread.run"` + - `agent: Agent{ agent_name}` - - `parallel_tool_calls: bool` + 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. + - `agent_name: String` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + The canonical name of the agent that produced this item. - Details on the action required to continue the run. Will be `null` if no action is required. + - `content: Array[Content{ text, type}]` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + Reasoning text content. - Details on the tool outputs needed for this run to continue. + - `text: String` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + The reasoning text from the model. - A list of the relevant tool calls. + - `type: :reasoning_text` - - `id: String` + The type of the reasoning text. Always `reasoning_text`. - 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. + - `:reasoning_text` - - `function: Function{ arguments, name}` + - `encrypted_content: String` - The function definition. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `arguments: String` + - `status: :in_progress | :completed | :incomplete` - The arguments that the model expects you to pass to the function. + 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 function. + - `:completed` - - `type: :function` + - `:incomplete` - The type of tool call the output is required for. For now, this is always `function`. + - `class BetaResponseCompactionItemParam` - - `:function` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `type: :submit_tool_outputs` + - `encrypted_content: String` - For now, this is always `submit_tool_outputs`. + The encrypted content of the compaction summary. - - `:submit_tool_outputs` + - `type: :compaction` - - `response_format: AssistantResponseFormatOption` + The type of the item. Always `compaction`. - 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`. + - `:compaction` - 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: String` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The ID of the compaction 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: Agent{ agent_name}` - - `AssistantResponseFormatOption = :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. - - `class ResponseFormatText` + - `class ImageGenerationCall` - Default response format. Used to generate text responses. + An image generation request made by the model. - - `type: :text` + - `id: String` - The type of response format being defined. Always `text`. + The unique ID of the image generation call. - - `:text` + - `result: String` - - `class ResponseFormatJSONObject` + The generated image encoded in 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. + - `status: :in_progress | :completed | :generating | :failed` - - `type: :json_object` + The status of the image generation call. - The type of response format being defined. Always `json_object`. + - `:in_progress` - - `:json_object` + - `:completed` - - `class ResponseFormatJSONSchema` + - `:generating` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:failed` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `type: :image_generation_call` - Structured Outputs configuration options, including a JSON Schema. + The type of the image generation call. Always `image_generation_call`. - - `name: String` + - `:image_generation_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. + - `agent: Agent{ agent_name}` - - `description: String` + The agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent_name: String` - - `schema: Hash[Symbol, untyped]` + 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/). + - `class BetaResponseCodeInterpreterToolCall` - - `strict: bool` + A tool call to run code. - 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). + - `id: String` - - `type: :json_schema` + The unique ID of the code interpreter tool call. - The type of response format being defined. Always `json_schema`. + - `code: String` - - `:json_schema` + The code to run, or null if not available. - - `started_at: Integer` + - `container_id: String` - The Unix timestamp (in seconds) for when the run was started. + The ID of the container used to run the code. - - `status: untyped` + - `outputs: Array[Logs{ logs, type} | Image{ 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 ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `class Logs` - - `tool_choice: AssistantToolChoiceOption` + The logs output from the code interpreter. - 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. + - `logs: String` - - `Auto = :none | :auto | :required` + The logs output from the code interpreter. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `type: :logs` - - `:none` + The type of the output. Always `logs`. - - `:auto` + - `:logs` - - `:required` + - `class Image` - - `class AssistantToolChoice` + The image output from the code interpreter. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `type: :image` - - `type: :function | :code_interpreter | :file_search` + The type of the output. Always `image`. - The type of the tool. If type is `function`, the function name must be set + - `:image` - - `:function` + - `url: String` - - `:code_interpreter` + The URL of the image output from the code interpreter. - - `:file_search` + - `status: :in_progress | :completed | :incomplete | 2 more` - - `function: AssistantToolChoiceFunction` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `name: String` + - `:in_progress` - The name of the function to call. + - `:completed` - - `tools: Array[untyped]` + - `:incomplete` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:interpreting` - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + - `:failed` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: :code_interpreter_call` - - `type: :auto | :last_messages` + The type of the code interpreter tool call. Always `code_interpreter_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`. + - `:code_interpreter_call` - - `:auto` + - `agent: Agent{ agent_name}` - - `:last_messages` + The agent that produced this item. - - `last_messages: Integer` + - `agent_name: String` - The number of most recent messages from the thread when constructing the context for the run. + The canonical name of the agent that produced this item. - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `class LocalShellCall` - 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 tool call to run a command on the local shell. - - `completion_tokens: Integer` + - `id: String` - Number of completion tokens used over the course of the run. + The unique ID of the local shell call. - - `prompt_tokens: Integer` + - `action: Action{ command, env, type, 3 more}` - Number of prompt tokens used over the course of the run. + Execute a shell command on the server. - - `total_tokens: Integer` + - `command: Array[String]` - Total number of tokens used (prompt + completion). + The command to run. - - `temperature: Float` + - `env: Hash[Symbol, String]` - The sampling temperature used for this run. If not set, defaults to 1. + Environment variables to set for the command. - - `top_p: Float` + - `type: :exec` - The nucleus sampling value used for this run. If not set, defaults to 1. + The type of the local shell action. Always `exec`. -### Example + - `:exec` -```ruby -require "openai" + - `timeout_ms: Integer` -openai = OpenAI::Client.new(api_key: "My API Key") + Optional timeout in milliseconds for the command. -page = openai.beta.threads.runs.list("thread_id") + - `user: String` -puts(page) -``` + Optional user to run the command as. -#### Response + - `working_directory: String` -```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": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "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" -} -``` + Optional working directory to run the command in. -## Create run + - `call_id: String` -`beta.threads.runs.create(thread_id, **kwargs) -> Run` + The unique ID of the local shell tool call generated by the model. -**post** `/threads/{thread_id}/runs` + - `status: :in_progress | :completed | :incomplete` -Create run + The status of the local shell call. -### Parameters + - `:in_progress` -- `thread_id: String` + - `:completed` -- `assistant_id: String` + - `:incomplete` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + - `type: :local_shell_call` -- `include: Array[RunStepInclude]` + The type of the local shell call. Always `local_shell_call`. - 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. + - `: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. + - `agent: Agent{ agent_name}` - - `:"step_details.tool_calls[*].file_search.results[*].content"` + The agent that produced this item. -- `additional_instructions: String` + - `agent_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. + The canonical name of the agent that produced this item. -- `additional_messages: Array[AdditionalMessage{ content, role, attachments, metadata}]` + - `class LocalShellCallOutput` - Adds additional messages to the thread before creating the run. + The output of a local shell tool call. - - `content: String | Array[MessageContentPartParam]` + - `id: String` - The text contents of the message. + The unique ID of the local shell tool call generated by the model. - - `String = String` + - `output: String` - The text contents of the message. + A JSON string of the output of the local shell tool call. - - `ArrayOfContentParts = Array[MessageContentPartParam]` + - `type: :local_shell_call_output` - 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 type of the local shell tool call output. Always `local_shell_call_output`. - - `class ImageFileContentBlock` + - `:local_shell_call_output` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `agent: Agent{ agent_name}` - - `image_file: ImageFile` + The agent that produced this item. - - `file_id: String` + - `agent_name: 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 canonical name of the agent that produced this item. - - `detail: :auto | :low | :high` + - `status: :in_progress | :completed | :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`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `:auto` + - `:in_progress` - - `:low` + - `:completed` - - `:high` + - `:incomplete` - - `type: :image_file` + - `class ShellCall` - Always `image_file`. + A tool representing a request to execute one or more shell commands. - - `:image_file` + - `action: Action{ commands, max_output_length, timeout_ms}` - - `class ImageURLContentBlock` + The shell commands and limits that describe how to run the tool call. - References an image URL in the content of a message. + - `commands: Array[String]` - - `image_url: ImageURL` + Ordered shell commands for the execution environment to run. - - `url: String` + - `max_output_length: Integer` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `detail: :auto | :low | :high` + - `timeout_ms: Integer` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `:auto` + - `call_id: String` - - `:low` + The unique ID of the shell tool call generated by the model. - - `:high` + - `type: :shell_call` - - `type: :image_url` + The type of the item. Always `shell_call`. - The type of the content part. + - `:shell_call` - - `:image_url` + - `id: String` - - `class TextContentBlockParam` + The unique ID of the shell tool call. Populated when this item is returned via API. - The text content that is part of a message. + - `agent: Agent{ agent_name}` - - `text: String` + The agent that produced this item. - Text content to be sent to the model + - `agent_name: String` - - `type: :text` + The canonical name of the agent that produced this item. - Always `text`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:text` + The execution context that produced this tool call. - - `role: :user | :assistant` + - `class Direct` - The role of the entity that is creating the message. Allowed values include: + - `type: :direct` - - `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 caller type. Always `direct`. - - `:user` + - `:direct` - - `:assistant` + - `class Program` - - `attachments: Array[Attachment{ file_id, tools}]` + - `caller_id: String` - A list of files attached to the message, and the tools they should be added to. + The call ID of the program item that produced this tool call. - - `file_id: String` + - `type: :program` - The ID of the file to attach to the message. + The caller type. Always `program`. - - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` + - `:program` - The tools to add this file to. + - `environment: BetaLocalEnvironment | BetaContainerReference` - - `class CodeInterpreterTool` + The environment to execute the shell commands in. - - `type: :code_interpreter` + - `class BetaLocalEnvironment` - The type of tool being defined: `code_interpreter` + - `class BetaContainerReference` - - `:code_interpreter` + - `status: :in_progress | :completed | :incomplete` - - `class FileSearch` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: :file_search` + - `:in_progress` - The type of tool being defined: `file_search` + - `:completed` - - `:file_search` + - `:incomplete` - - `metadata: Metadata` + - `class ShellCallOutput` - Set of 16 key-value pairs that can be attached to an object. 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 streamed output items emitted by a shell tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `call_id: String` -- `instructions: String` + The unique ID of the shell tool call generated by the model. - 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. + - `output: Array[BetaResponseFunctionShellCallOutputContent]` -- `max_completion_tokens: Integer` + Captured chunks of stdout and stderr output, along with their associated outcomes. - 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. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` -- `max_prompt_tokens: Integer` + The exit or timeout outcome associated with this shell call. - 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. + - `class Timeout` -- `metadata: Metadata` + Indicates that the shell call exceeded its configured time limit. - Set of 16 key-value pairs that can be attached to an object. 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: :timeout` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The outcome type. Always `timeout`. -- `model: String | ChatModel` + - `:timeout` - 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. + - `class Exit` - - `String = String` + Indicates that the shell commands finished and returned an exit code. - - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + - `exit_code: Integer` - - `:"gpt-5.6-sol"` + The exit code returned by the shell process. - - `:"gpt-5.6-terra"` + - `type: :exit` - - `:"gpt-5.6-luna"` + The outcome type. Always `exit`. - - `:"gpt-5.4"` + - `:exit` - - `:"gpt-5.4-mini"` + - `stderr: String` - - `:"gpt-5.4-nano"` + Captured stderr output for the shell call. - - `:"gpt-5.4-mini-2026-03-17"` + - `stdout: String` - - `:"gpt-5.4-nano-2026-03-17"` + Captured stdout output for the shell call. - - `:"gpt-5.3-chat-latest"` + - `type: :shell_call_output` - - `:"gpt-5.2"` + The type of the item. Always `shell_call_output`. - - `:"gpt-5.2-2025-12-11"` + - `:shell_call_output` - - `:"gpt-5.2-chat-latest"` + - `id: String` - - `:"gpt-5.2-pro"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `:"gpt-5.2-pro-2025-12-11"` + - `agent: Agent{ agent_name}` - - `:"gpt-5.1"` + The agent that produced this item. - - `:"gpt-5.1-2025-11-13"` + - `agent_name: String` - - `:"gpt-5.1-codex"` + The canonical name of the agent that produced this item. - - `:"gpt-5.1-mini"` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:"gpt-5.1-chat-latest"` + The execution context that produced this tool call. - - `:"gpt-5"` + - `class Direct` - - `:"gpt-5-mini"` + - `type: :direct` - - `:"gpt-5-nano"` + The caller type. Always `direct`. - - `:"gpt-5-2025-08-07"` + - `:direct` - - `:"gpt-5-mini-2025-08-07"` + - `class Program` - - `:"gpt-5-nano-2025-08-07"` + - `caller_id: String` - - `:"gpt-5-chat-latest"` + The call ID of the program item that produced this tool call. - - `:"gpt-4.1"` + - `type: :program` - - `:"gpt-4.1-mini"` + The caller type. Always `program`. - - `:"gpt-4.1-nano"` + - `:program` - - `:"gpt-4.1-2025-04-14"` + - `max_output_length: Integer` - - `:"gpt-4.1-mini-2025-04-14"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `:"gpt-4.1-nano-2025-04-14"` + - `status: :in_progress | :completed | :incomplete` - - `:"o4-mini"` + The status of the shell call output. - - `:"o4-mini-2025-04-16"` + - `:in_progress` - - `:o3` + - `:completed` - - `:"o3-2025-04-16"` + - `:incomplete` - - `:"o3-mini"` + - `class ApplyPatchCall` - - `:"o3-mini-2025-01-31"` + A tool call representing a request to create, delete, or update files using diff patches. - - `:o1` + - `call_id: String` - - `:"o1-2024-12-17"` + The unique ID of the apply patch tool call generated by the model. - - `:"o1-preview"` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `:"o1-preview-2024-09-12"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `:"o1-mini"` + - `class CreateFile` - - `:"o1-mini-2024-09-12"` + Instruction for creating a new file via the apply_patch tool. - - `:"gpt-4o"` + - `diff: String` - - `:"gpt-4o-2024-11-20"` + Unified diff content to apply when creating the file. - - `:"gpt-4o-2024-08-06"` + - `path: String` - - `:"gpt-4o-2024-05-13"` + Path of the file to create relative to the workspace root. - - `:"gpt-4o-audio-preview"` + - `type: :create_file` - - `:"gpt-4o-audio-preview-2024-10-01"` + The operation type. Always `create_file`. - - `:"gpt-4o-audio-preview-2024-12-17"` + - `:create_file` - - `:"gpt-4o-audio-preview-2025-06-03"` + - `class DeleteFile` - - `:"gpt-4o-mini-audio-preview"` + Instruction for deleting an existing file via the apply_patch tool. - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `path: String` - - `:"gpt-4o-search-preview"` + Path of the file to delete relative to the workspace root. - - `:"gpt-4o-mini-search-preview"` + - `type: :delete_file` - - `:"gpt-4o-search-preview-2025-03-11"` + The operation type. Always `delete_file`. - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `:delete_file` - - `:"chatgpt-4o-latest"` + - `class UpdateFile` - - `:"codex-mini-latest"` + Instruction for updating an existing file via the apply_patch tool. - - `:"gpt-4o-mini"` + - `diff: String` - - `:"gpt-4o-mini-2024-07-18"` + Unified diff content to apply to the existing file. - - `:"gpt-4-turbo"` + - `path: String` - - `:"gpt-4-turbo-2024-04-09"` + Path of the file to update relative to the workspace root. - - `:"gpt-4-0125-preview"` + - `type: :update_file` - - `:"gpt-4-turbo-preview"` + The operation type. Always `update_file`. - - `:"gpt-4-1106-preview"` + - `:update_file` - - `:"gpt-4-vision-preview"` + - `status: :in_progress | :completed` - - `:"gpt-4"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:"gpt-4-0314"` + - `:in_progress` - - `:"gpt-4-0613"` + - `:completed` - - `:"gpt-4-32k"` + - `type: :apply_patch_call` - - `:"gpt-4-32k-0314"` + The type of the item. Always `apply_patch_call`. - - `:"gpt-4-32k-0613"` + - `:apply_patch_call` - - `:"gpt-3.5-turbo"` + - `id: String` - - `:"gpt-3.5-turbo-16k"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `:"gpt-3.5-turbo-0301"` + - `agent: Agent{ agent_name}` - - `:"gpt-3.5-turbo-0613"` + The agent that produced this item. - - `:"gpt-3.5-turbo-1106"` + - `agent_name: String` - - `:"gpt-3.5-turbo-0125"` + The canonical name of the agent that produced this item. - - `:"gpt-3.5-turbo-16k-0613"` + - `caller_: Direct{ type} | Program{ caller_id, type}` -- `parallel_tool_calls: bool` + The execution context that produced this tool call. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `class Direct` -- `reasoning_effort: ReasoningEffort` + - `type: :direct` - 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 caller type. Always `direct`. - - `:none` + - `:direct` - - `:minimal` + - `class Program` - - `:low` + - `caller_id: String` - - `:medium` + The call ID of the program item that produced this tool call. - - `:high` + - `type: :program` - - `:xhigh` + The caller type. Always `program`. - - `:max` + - `:program` -- `response_format: AssistantResponseFormatOption` + - `class ApplyPatchCallOutput` - 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 streamed output emitted by an apply patch 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). + - `call_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 apply patch tool call generated by 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. + - `status: :completed | :failed` - - `AssistantResponseFormatOption = :auto` + The status of the apply patch tool call output. One of `completed` or `failed`. - `auto` is the default value + - `:completed` - - `:auto` + - `:failed` - - `class ResponseFormatText` + - `type: :apply_patch_call_output` - Default response format. Used to generate text responses. + The type of the item. Always `apply_patch_call_output`. - - `type: :text` + - `:apply_patch_call_output` - The type of response format being defined. Always `text`. + - `id: String` - - `:text` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class ResponseFormatJSONObject` + - `agent: Agent{ 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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class ResponseFormatJSONSchema` + The execution context 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). + - `class Direct` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `type: :direct` - Structured Outputs configuration options, including a JSON Schema. + The caller type. Always `direct`. - - `name: String` + - `:direct` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `class Program` - - `description: String` + - `caller_id: String` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The call ID of the program item that produced this tool call. - - `schema: Hash[Symbol, untyped]` + - `type: :program` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The caller type. Always `program`. - - `strict: bool` + - `: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](https://platform.openai.com/docs/guides/structured-outputs). + - `output: String` - - `type: :json_schema` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The type of response format being defined. Always `json_schema`. + - `class McpListTools` - - `:json_schema` + A list of tools available on an MCP server. -- `stream: bool` + - `id: String` - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + The unique ID of the list. -- `temperature: Float` + - `server_label: 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 label of the MCP server. -- `tool_choice: AssistantToolChoiceOption` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - 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 tools available on the server. - - `Auto = :none | :auto | :required` + - `input_schema: untyped` - `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 JSON schema describing the tool's input. - - `:none` + - `name: String` - - `:auto` + The name of the tool. - - `:required` + - `annotations: untyped` - - `class AssistantToolChoice` + Additional annotations about the tool. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `description: String` - - `type: :function | :code_interpreter | :file_search` + The description of the tool. - The type of the tool. If type is `function`, the function name must be set + - `type: :mcp_list_tools` - - `:function` + The type of the item. Always `mcp_list_tools`. - - `:code_interpreter` + - `:mcp_list_tools` - - `:file_search` + - `agent: Agent{ agent_name}` - - `function: AssistantToolChoiceFunction` + 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. -- `tools: Array[untyped]` + - `error: String` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + Error message if the server could not list tools. -- `top_p: Float` + - `class McpApprovalRequest` - 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 request for human approval of a tool invocation. - We generally recommend altering this or temperature but not both. + - `id: String` -- `truncation_strategy: TruncationStrategy{ type, last_messages}` + The unique ID of the approval request. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `arguments: String` - - `type: :auto | :last_messages` + A JSON string of arguments for the tool. - 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`. + - `name: String` - - `:auto` + The name of the tool to run. - - `:last_messages` + - `server_label: String` - - `last_messages: Integer` + The label of the MCP server making the request. - The number of most recent messages from the thread when constructing the context for the run. + - `type: :mcp_approval_request` -### Returns + The type of the item. Always `mcp_approval_request`. -- `class Run` + - `:mcp_approval_request` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent: Agent{ agent_name}` - - `id: String` + The agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `agent_name: String` - - `assistant_id: String` + The canonical name of the agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `class McpApprovalResponse` - - `cancelled_at: Integer` + A response to an MCP approval request. - The Unix timestamp (in seconds) for when the run was cancelled. + - `approval_request_id: String` - - `completed_at: Integer` + The ID of the approval request being answered. - The Unix timestamp (in seconds) for when the run was completed. + - `approve: bool` - - `created_at: Integer` + Whether the request was approved. - The Unix timestamp (in seconds) for when the run was created. + - `type: :mcp_approval_response` - - `expires_at: Integer` + The type of the item. Always `mcp_approval_response`. - The Unix timestamp (in seconds) for when the run will expire. + - `:mcp_approval_response` - - `failed_at: Integer` + - `id: String` - The Unix timestamp (in seconds) for when the run failed. + The unique ID of the approval response - - `incomplete_details: IncompleteDetails{ reason}` + - `agent: Agent{ agent_name}` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The agent that produced this item. - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `agent_name: 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 canonical name of the agent that produced this item. - - `:max_completion_tokens` + - `reason: String` - - `:max_prompt_tokens` + Optional reason for the decision. - - `instructions: String` + - `class McpCall` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + An invocation of a tool on an MCP server. - - `last_error: LastError{ code, message}` + - `id: String` - The last error associated with this run. Will be `null` if there are no errors. + The unique ID of the tool call. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `arguments: String` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + A JSON string of the arguments passed to the tool. - - `:server_error` + - `name: String` - - `:rate_limit_exceeded` + The name of the tool that was run. - - `:invalid_prompt` + - `server_label: String` - - `message: String` + The label of the MCP server running the tool. - A human-readable description of the error. + - `type: :mcp_call` - - `max_completion_tokens: Integer` + The type of the item. Always `mcp_call`. - The maximum number of completion tokens specified to have been used over the course of the run. + - `:mcp_call` - - `max_prompt_tokens: Integer` + - `agent: Agent{ agent_name}` - The maximum number of prompt tokens specified to have been used over the course of the run. + The agent that produced this item. - - `metadata: Metadata` + - `agent_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 canonical name of the agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `approval_request_id: String` - - `model: 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 model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `error: String` - - `object: :"thread.run"` + The error from the tool call, if any. - The object type, which is always `thread.run`. + - `output: String` - - `:"thread.run"` + The output from the tool call. - - `parallel_tool_calls: bool` + - `status: :in_progress | :completed | :incomplete | 2 more` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `required_action: RequiredAction{ submit_tool_outputs, type}` + - `:in_progress` - Details on the action required to continue the run. Will be `null` if no action is required. + - `:completed` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + - `:incomplete` - Details on the tool outputs needed for this run to continue. + - `:calling` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + - `:failed` - A list of the relevant tool calls. + - `class BetaResponseCustomToolCallOutput` - - `id: String` + The output of a custom tool call from your code, being sent back to the model. - 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. + - `call_id: String` - - `function: Function{ arguments, name}` + The call ID, used to map this custom tool call output to a custom tool call. - The function definition. + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `arguments: String` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The arguments that the model expects you to pass to the function. + - `String = String` - - `name: String` + A string of the output of the custom tool call. - The name of the function. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `type: :function` + Text, image, or file output of the custom tool call. - The type of tool call the output is required for. For now, this is always `function`. + - `class BetaResponseInputText` - - `:function` + A text input to the model. - - `type: :submit_tool_outputs` + - `class BetaResponseInputImage` - For now, this is always `submit_tool_outputs`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:submit_tool_outputs` + - `class BetaResponseInputFile` - - `response_format: AssistantResponseFormatOption` + A file input to the model. - 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: :custom_tool_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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the custom tool call output. Always `custom_tool_call_output`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `:custom_tool_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. + - `id: String` - - `AssistantResponseFormatOption = :auto` + The unique ID of the custom tool call output in the OpenAI platform. - `auto` is the default value + - `agent: Agent{ agent_name}` - - `:auto` + The agent that produced this item. - - `class ResponseFormatText` + - `agent_name: String` - Default response format. Used to generate text responses. + The canonical name of the agent that produced this item. - - `type: :text` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The type of response format being defined. Always `text`. + The execution context that produced this tool call. - - `:text` + - `class Direct` - - `class ResponseFormatJSONObject` + - `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. + The caller type. Always `direct`. - - `type: :json_object` + - `:direct` - The type of response format being defined. Always `json_object`. + - `class Program` - - `:json_object` + - `caller_id: String` - - `class ResponseFormatJSONSchema` + 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` - - `json_schema: JSONSchema{ name, description, schema, strict}` + The caller type. Always `program`. - Structured Outputs configuration options, including a JSON Schema. + - `:program` - - `name: String` + - `class BetaResponseCustomToolCall` - 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 call to a custom tool created by the model. - - `description: 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. + An identifier used to map this custom tool call to a tool call output. - - `schema: Hash[Symbol, untyped]` + - `input: 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 input for the custom tool call generated by the model. - - `strict: bool` + - `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 name of the custom tool being called. - - `type: :json_schema` + - `type: :custom_tool_call` - The type of response format being defined. Always `json_schema`. + The type of the custom tool call. Always `custom_tool_call`. - - `:json_schema` + - `:custom_tool_call` - - `started_at: Integer` + - `id: String` - The Unix timestamp (in seconds) for when the run was started. + The unique ID of the custom tool call in the OpenAI platform. - - `status: untyped` + - `agent: Agent{ agent_name}` - - `thread_id: String` + The agent that produced this item. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `agent_name: String` - - `tool_choice: AssistantToolChoiceOption` + The canonical name of 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. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `Auto = :none | :auto | :required` + The execution context that produced this tool call. - `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. + - `class Direct` - - `:none` + - `type: :direct` - - `:auto` + - `:direct` - - `:required` + - `class Program` - - `class AssistantToolChoice` + - `caller_id: String` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The call ID of the program item that produced this tool call. - - `type: :function | :code_interpreter | :file_search` + - `type: :program` - The type of the tool. If type is `function`, the function name must be set + - `:program` - - `:function` + - `namespace: String` - - `:code_interpreter` + The namespace of the custom tool being called. - - `:file_search` + - `class CompactionTrigger` - - `function: AssistantToolChoiceFunction` + Compacts the current context. Must be the final input item. - - `name: String` + - `type: :compaction_trigger` - The name of the function to call. + The type of the item. Always `compaction_trigger`. - - `tools: Array[untyped]` + - `:compaction_trigger` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent: Agent{ agent_name}` - - `truncation_strategy: TruncationStrategy{ 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 | :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`. + - `class ItemReference` - - `:auto` + An internal identifier for an item to reference. - - `:last_messages` + - `id: String` - - `last_messages: Integer` + The ID of the item to reference. - The number of most recent messages from the thread when constructing the context for the run. + - `agent: Agent{ agent_name}` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + 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.). + - `agent_name: String` - - `completion_tokens: Integer` + The canonical name of the agent that produced this item. - Number of completion tokens used over the course of the run. + - `type: :item_reference` - - `prompt_tokens: Integer` + The type of item to reference. Always `item_reference`. - Number of prompt tokens used over the course of the run. + - `:item_reference` - - `total_tokens: Integer` + - `class Program` - Total number of tokens used (prompt + completion). + - `id: String` - - `temperature: Float` + The unique ID of this program item. - The sampling temperature used for this run. If not set, defaults to 1. + - `call_id: String` - - `top_p: Float` + The stable call ID of the program item. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `code: String` -### Example + The JavaScript source executed by programmatic tool calling. -```ruby -require "openai" + - `fingerprint: String` -openai = OpenAI::Client.new(api_key: "My API Key") + Opaque program replay fingerprint that must be round-tripped. -run = openai.beta.threads.runs.create("thread_id", assistant_id: "assistant_id") + - `type: :program` -puts(run) -``` + The item 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": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `agent: Agent{ agent_name}` -## Retrieve run + The agent that produced this item. -`beta.threads.runs.retrieve(run_id, **kwargs) -> Run` + - `agent_name: String` -**get** `/threads/{thread_id}/runs/{run_id}` + The canonical name of the agent that produced this item. -Retrieve run + - `class ProgramOutput` -### Parameters + - `id: String` -- `thread_id: String` + The unique ID of this program output item. -- `run_id: String` + - `call_id: String` -### Returns + The call ID of the program item. -- `class Run` + - `result: String` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The result produced by the program item. - - `id: String` + - `status: :completed | :incomplete` - The identifier, which can be referenced in API endpoints. + The terminal status of the program output. - - `assistant_id: String` + - `:completed` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `:incomplete` - - `cancelled_at: Integer` + - `type: :program_output` - The Unix timestamp (in seconds) for when the run was cancelled. + The item type. Always `program_output`. - - `completed_at: Integer` + - `:program_output` - The Unix timestamp (in seconds) for when the run was completed. + - `agent: Agent{ agent_name}` - - `created_at: Integer` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was created. + - `agent_name: String` - - `expires_at: Integer` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run will expire. + - `metadata: Hash[Symbol, String]` - - `failed_at: Integer` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The Unix timestamp (in seconds) for when the run failed. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `incomplete_details: IncompleteDetails{ reason}` + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - Details on why the run is incomplete. Will be `null` if the run is not 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](https://platform.openai.com/docs/models) + to browse and compare available models. - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + 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. - - `:max_completion_tokens` + - `:"gpt-5.6-sol"` - - `:max_prompt_tokens` + - `:"gpt-5.6-terra"` - - `instructions: String` + - `:"gpt-5.6-luna"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:"gpt-5.4"` - - `last_error: LastError{ code, message}` + - `:"gpt-5.4-mini"` - The last error associated with this run. Will be `null` if there are no errors. + - `:"gpt-5.4-nano"` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `:"gpt-5.4-mini-2026-03-17"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `:"gpt-5.4-nano-2026-03-17"` - - `:server_error` + - `:"gpt-5.3-chat-latest"` - - `:rate_limit_exceeded` + - `:"gpt-5.2"` - - `:invalid_prompt` + - `:"gpt-5.2-2025-12-11"` - - `message: String` + - `:"gpt-5.2-chat-latest"` - A human-readable description of the error. + - `:"gpt-5.2-pro"` - - `max_completion_tokens: Integer` + - `:"gpt-5.2-pro-2025-12-11"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `:"gpt-5.1"` - - `max_prompt_tokens: Integer` + - `:"gpt-5.1-2025-11-13"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `:"gpt-5.1-codex"` - - `metadata: Metadata` + - `:"gpt-5.1-mini"` - Set of 16 key-value pairs that can be attached to an object. 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-5.1-chat-latest"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:"gpt-5"` - - `model: String` + - `:"gpt-5-mini"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:"gpt-5-nano"` - - `object: :"thread.run"` + - `:"gpt-5-2025-08-07"` - The object type, which is always `thread.run`. + - `:"gpt-5-mini-2025-08-07"` - - `:"thread.run"` + - `:"gpt-5-nano-2025-08-07"` - - `parallel_tool_calls: bool` + - `:"gpt-5-chat-latest"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `:"gpt-4.1"` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + - `:"gpt-4.1-mini"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `:"gpt-4.1-nano"` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + - `:"gpt-4.1-2025-04-14"` - Details on the tool outputs needed for this run to continue. + - `:"gpt-4.1-mini-2025-04-14"` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + - `:"gpt-4.1-nano-2025-04-14"` - A list of the relevant tool calls. + - `:"o4-mini"` - - `id: String` + - `:"o4-mini-2025-04-16"` - 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. + - `:o3` - - `function: Function{ arguments, name}` + - `:"o3-2025-04-16"` - The function definition. + - `:"o3-mini"` - - `arguments: String` + - `:"o3-mini-2025-01-31"` - The arguments that the model expects you to pass to the function. + - `:o1` - - `name: String` + - `:"o1-2024-12-17"` - The name of the function. + - `:"o1-preview"` - - `type: :function` + - `:"o1-preview-2024-09-12"` - The type of tool call the output is required for. For now, this is always `function`. + - `:"o1-mini"` - - `:function` + - `:"o1-mini-2024-09-12"` - - `type: :submit_tool_outputs` + - `:"gpt-4o"` - For now, this is always `submit_tool_outputs`. + - `:"gpt-4o-2024-11-20"` - - `:submit_tool_outputs` + - `:"gpt-4o-2024-08-06"` - - `response_format: AssistantResponseFormatOption` + - `:"gpt-4o-2024-05-13"` - 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`. + - `:"gpt-4o-audio-preview"` - 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). + - `:"gpt-4o-audio-preview-2024-10-01"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `:"gpt-4o-audio-preview-2024-12-17"` - **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. + - `:"gpt-4o-audio-preview-2025-06-03"` - - `AssistantResponseFormatOption = :auto` + - `:"gpt-4o-mini-audio-preview"` - `auto` is the default value + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - - `:auto` + - `:"gpt-4o-search-preview"` - - `class ResponseFormatText` + - `:"gpt-4o-mini-search-preview"` - Default response format. Used to generate text responses. + - `:"gpt-4o-search-preview-2025-03-11"` - - `type: :text` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - The type of response format being defined. Always `text`. + - `:"chatgpt-4o-latest"` - - `:text` + - `:"codex-mini-latest"` - - `class ResponseFormatJSONObject` + - `:"gpt-4o-mini"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `:"gpt-4o-mini-2024-07-18"` - - `type: :json_object` + - `:"gpt-4-turbo"` - The type of response format being defined. Always `json_object`. + - `:"gpt-4-turbo-2024-04-09"` - - `:json_object` + - `:"gpt-4-0125-preview"` - - `class ResponseFormatJSONSchema` + - `:"gpt-4-turbo-preview"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:"gpt-4-1106-preview"` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `:"gpt-4-vision-preview"` - Structured Outputs configuration options, including a JSON Schema. + - `:"gpt-4"` - - `name: String` + - `:"gpt-4-0314"` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `:"gpt-4-0613"` - - `description: String` + - `:"gpt-4-32k"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:"gpt-4-32k-0314"` - - `schema: Hash[Symbol, untyped]` + - `:"gpt-4-32k-0613"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `:"gpt-3.5-turbo"` - - `strict: bool` + - `:"gpt-3.5-turbo-16k"` - 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). + - `:"gpt-3.5-turbo-0301"` - - `type: :json_schema` + - `:"gpt-3.5-turbo-0613"` - The type of response format being defined. Always `json_schema`. + - `:"gpt-3.5-turbo-1106"` - - `:json_schema` + - `:"gpt-3.5-turbo-0125"` - - `started_at: Integer` + - `:"gpt-3.5-turbo-16k-0613"` - The Unix timestamp (in seconds) for when the run was started. + - `:"o1-pro"` - - `status: untyped` + - `:"o1-pro-2025-03-19"` - - `thread_id: String` + - `:"o3-pro"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `:"o3-pro-2025-06-10"` - - `tool_choice: AssistantToolChoiceOption` + - `:"o3-deep-research"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `:"o3-deep-research-2025-06-26"` - - `Auto = :none | :auto | :required` + - `:"o4-mini-deep-research"` - `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. + - `:"o4-mini-deep-research-2025-06-26"` - - `:none` + - `:"computer-use-preview"` - - `:auto` + - `:"computer-use-preview-2025-03-11"` - - `:required` + - `:"gpt-5-codex"` - - `class AssistantToolChoice` + - `:"gpt-5-pro"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `:"gpt-5-pro-2025-10-06"` - - `type: :function | :code_interpreter | :file_search` + - `:"gpt-5.1-codex-max"` - The type of the tool. If type is `function`, the function name must be set + - `String = String` - - `:function` + - `object: :response` - - `:code_interpreter` + The object type of this resource - always set to `response`. - - `:file_search` + - `:response` - - `function: AssistantToolChoiceFunction` + - `output: Array[BetaResponseOutputItem]` - - `name: String` + An array of content items generated by the model. - The name of the function to call. + - 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. - - `tools: Array[untyped]` + - `class BetaResponseOutputMessage` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + An output message from the model. - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + - `class BetaResponseFileSearchToolCall` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + 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: :auto | :last_messages` + - `class BetaResponseFunctionToolCall` - 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 call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:auto` + - `class BetaResponseFunctionToolCallOutputItem` - - `:last_messages` + - `id: String` - - `last_messages: Integer` + The unique ID of the function call tool output. - The number of most recent messages from the thread when constructing the context for the run. + - `call_id: String` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + The unique ID of the function tool call generated by the model. - 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.). + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `completion_tokens: Integer` + The output from the function call generated by your code. + Can be a string or an list of output content. - Number of completion tokens used over the course of the run. + - `String = String` - - `prompt_tokens: Integer` + A string of the output of the function call. - Number of prompt tokens used over the course of the run. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `total_tokens: Integer` + Text, image, or file output of the function call. - Total number of tokens used (prompt + completion). + - `class BetaResponseInputText` - - `temperature: Float` + A text input to the model. - The sampling temperature used for this run. If not set, defaults to 1. + - `class BetaResponseInputImage` - - `top_p: Float` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The nucleus sampling value used for this run. If not set, defaults to 1. + - `class BetaResponseInputFile` -### Example + A file input to the model. -```ruby -require "openai" + - `status: :in_progress | :completed | :incomplete` -openai = OpenAI::Client.new(api_key: "My API Key") + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -run = openai.beta.threads.runs.retrieve("run_id", thread_id: "thread_id") + - `:in_progress` -puts(run) -``` + - `:completed` -#### Response + - `:incomplete` -```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": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `type: :function_call_output` -## Modify run + The type of the function tool call output. Always `function_call_output`. -`beta.threads.runs.update(run_id, **kwargs) -> Run` + - `:function_call_output` -**post** `/threads/{thread_id}/runs/{run_id}` + - `agent: Agent{ agent_name}` -Modify run + The agent that produced this item. -### Parameters + - `agent_name: String` -- `thread_id: String` + The canonical name of the agent that produced this item. -- `run_id: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` -- `metadata: Metadata` + The execution context that produced this tool call. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `class Direct` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: :direct` -### Returns + The caller type. Always `direct`. -- `class Run` + - `:direct` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class Program` - - `id: String` + - `caller_id: String` - The identifier, which can be referenced in API endpoints. + The call ID of the program item that produced this tool call. - - `assistant_id: String` + - `type: :program` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The caller type. Always `program`. - - `cancelled_at: Integer` + - `:program` - The Unix timestamp (in seconds) for when the run was cancelled. + - `created_by: String` - - `completed_at: Integer` + The identifier of the actor that created the item. - The Unix timestamp (in seconds) for when the run was completed. + - `class AgentMessage` - - `created_at: Integer` + - `id: String` - The Unix timestamp (in seconds) for when the run was created. + The unique ID of the agent message. - - `expires_at: Integer` + - `author: String` - The Unix timestamp (in seconds) for when the run will expire. + The sending agent identity. - - `failed_at: Integer` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - The Unix timestamp (in seconds) for when the run failed. + Encrypted content sent between agents. - - `incomplete_details: IncompleteDetails{ reason}` + - `class BetaResponseInputText` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + A text input to the model. - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `class BetaResponseOutputText` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + A text output from the model. - - `:max_completion_tokens` + - `class Text` - - `:max_prompt_tokens` + A text content. - - `instructions: String` + - `text: String` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: :text` - - `last_error: LastError{ code, message}` + - `:text` - The last error associated with this run. Will be `null` if there are no errors. + - `class SummaryText` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + A summary text from the model. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `text: String` - - `:server_error` + A summary of the reasoning output from the model so far. - - `:rate_limit_exceeded` + - `type: :summary_text` - - `:invalid_prompt` + The type of the object. Always `summary_text`. - - `message: String` + - `:summary_text` - A human-readable description of the error. + - `class ReasoningText` - - `max_completion_tokens: Integer` + Reasoning text from the model. - The maximum number of completion tokens specified to have been used over the course of the run. + - `text: String` - - `max_prompt_tokens: Integer` + The reasoning text from the model. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: :reasoning_text` - - `metadata: Metadata` + The type of the reasoning text. Always `reasoning_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. + - `:reasoning_text` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class BetaResponseOutputRefusal` - - `model: String` + A refusal from the model. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class BetaResponseInputImage` - - `object: :"thread.run"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The object type, which is always `thread.run`. + - `class ComputerScreenshot` - - `:"thread.run"` + A screenshot of a computer. - - `parallel_tool_calls: bool` + - `detail: :low | :high | :auto | :original` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `required_action: RequiredAction{ submit_tool_outputs, type}` + - `:low` - Details on the action required to continue the run. Will be `null` if no action is required. + - `:high` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + - `:auto` - Details on the tool outputs needed for this run to continue. + - `:original` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + - `file_id: String` - A list of the relevant tool calls. + The identifier of an uploaded file that contains the screenshot. - - `id: String` + - `image_url: 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 URL of the screenshot image. - - `function: Function{ arguments, name}` + - `type: :computer_screenshot` - The function definition. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `arguments: String` + - `:computer_screenshot` - The arguments that the model expects you to pass to the function. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 function. + - `mode: :explicit` - - `type: :function` + The breakpoint mode. Always `explicit`. - The type of tool call the output is required for. For now, this is always `function`. + - `:explicit` - - `:function` + - `class BetaResponseInputFile` - - `type: :submit_tool_outputs` + A file input to the model. - For now, this is always `submit_tool_outputs`. + - `class EncryptedContent` - - `:submit_tool_outputs` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `response_format: AssistantResponseFormatOption` + - `encrypted_content: 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`. + Opaque encrypted content. - 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: :encrypted_content` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The type of the input item. Always `encrypted_content`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `:encrypted_content` - - `AssistantResponseFormatOption = :auto` + - `recipient: String` - `auto` is the default value + The destination agent identity. - - `:auto` + - `type: :agent_message` - - `class ResponseFormatText` + The type of the item. Always `agent_message`. - Default response format. Used to generate text responses. + - `:agent_message` - - `type: :text` + - `agent: Agent{ agent_name}` - The type of response format being defined. Always `text`. + The agent that produced this item. - - `:text` + - `agent_name: String` - - `class ResponseFormatJSONObject` + The canonical name of 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. + - `class MultiAgentCall` - - `type: :json_object` + - `id: String` - The type of response format being defined. Always `json_object`. + The unique ID of the multi-agent call item. - - `:json_object` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `class ResponseFormatJSONSchema` + The multi-agent action to execute. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:spawn_agent` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `:interrupt_agent` - Structured Outputs configuration options, including a JSON Schema. + - `:list_agents` - - `name: String` + - `:send_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. + - `:followup_task` - - `description: String` + - `:wait_agent` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `arguments: String` - - `schema: Hash[Symbol, untyped]` + The JSON string of arguments generated for the action. - 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: bool` + The unique ID linking this call to its 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). + - `type: :multi_agent_call` - - `type: :json_schema` + The type of the multi-agent call. Always `multi_agent_call`. - The type of response format being defined. Always `json_schema`. + - `:multi_agent_call` - - `:json_schema` + - `agent: Agent{ agent_name}` - - `started_at: Integer` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was started. + - `agent_name: String` - - `status: untyped` + The canonical name of the agent that produced this item. - - `thread_id: String` + - `class MultiAgentCallOutput` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `id: String` - - `tool_choice: AssistantToolChoiceOption` + The unique ID of the multi-agent call output 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. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `Auto = :none | :auto | :required` + The multi-agent action that produced this result. - `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. + - `:spawn_agent` - - `:none` + - `:interrupt_agent` - - `:auto` + - `:list_agents` - - `:required` + - `:send_message` - - `class AssistantToolChoice` + - `:followup_task` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `:wait_agent` - - `type: :function | :code_interpreter | :file_search` + - `call_id: String` - The type of the tool. If type is `function`, the function name must be set + The unique ID of the multi-agent call. - - `:function` + - `output: Array[BetaResponseOutputText]` - - `:code_interpreter` + Text output returned by the multi-agent action. - - `:file_search` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `function: AssistantToolChoiceFunction` + The annotations of the text output. - - `name: String` + - `text: String` - The name of the function to call. + The text output from the model. - - `tools: Array[untyped]` + - `type: :output_text` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the output text. Always `output_text`. - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: :multi_agent_call_output` - - `type: :auto | :last_messages` + The type of the multi-agent result. Always `multi_agent_call_output`. - 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`. + - `:multi_agent_call_output` - - `:auto` + - `agent: Agent{ agent_name}` - - `:last_messages` + The agent that produced this item. - - `last_messages: Integer` + - `agent_name: String` - The number of most recent messages from the thread when constructing the context for the run. + The canonical name of the agent that produced this item. - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `class BetaResponseFunctionWebSearch` - 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 results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `completion_tokens: Integer` + - `class BetaResponseComputerToolCall` - Number of completion tokens used over the course of the run. + 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. - - `prompt_tokens: Integer` + - `class BetaResponseComputerToolCallOutputItem` - Number of prompt tokens used over the course of the run. + - `id: String` - - `total_tokens: Integer` + The unique ID of the computer call tool output. - Total number of tokens used (prompt + completion). + - `call_id: String` - - `temperature: Float` + The ID of the computer tool call that produced the output. - The sampling temperature used for this run. If not set, defaults to 1. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `top_p: Float` + A computer screenshot image used with the computer use tool. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `status: :completed | :incomplete | :failed | :in_progress` -### Example + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. -```ruby -require "openai" + - `:completed` -openai = OpenAI::Client.new(api_key: "My API Key") + - `:incomplete` -run = openai.beta.threads.runs.update("run_id", thread_id: "thread_id") + - `:failed` -puts(run) -``` + - `:in_progress` -#### Response + - `type: :computer_call_output` -```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": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The type of the computer tool call output. Always `computer_call_output`. -## Submit tool outputs to run + - `:computer_call_output` -`beta.threads.runs.submit_tool_outputs(run_id, **kwargs) -> Run` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + The safety checks reported by the API that have been acknowledged by the + developer. -Submit tool outputs to run + - `id: String` -### Parameters + The ID of the pending safety check. -- `thread_id: String` + - `code: String` -- `run_id: String` + The type of the pending safety check. -- `tool_outputs: Array[ToolOutput{ output, tool_call_id}]` + - `message: String` - A list of tools for which the outputs are being submitted. + Details about the pending safety check. - - `output: String` + - `agent: Agent{ agent_name}` - The output of the tool call to be submitted to continue the run. + The agent that produced this item. - - `tool_call_id: String` + - `agent_name: String` - The ID of the tool call in the `required_action` object within the run object the output is being submitted for. + The canonical name of the agent that produced this item. -- `stream: bool` + - `created_by: String` - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + The identifier of the actor that created the item. -### Returns + - `class BetaResponseReasoningItem` -- `class Run` + 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). - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class Program` - `id: String` - The identifier, which can be referenced in API endpoints. + The unique ID of the program 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 stable call ID of the program item. - - `cancelled_at: Integer` + - `code: String` - The Unix timestamp (in seconds) for when the run was cancelled. + The JavaScript source executed by programmatic tool calling. - - `completed_at: Integer` + - `fingerprint: String` - The Unix timestamp (in seconds) for when the run was completed. + Opaque program replay fingerprint that must be round-tripped. - - `created_at: Integer` + - `type: :program` - The Unix timestamp (in seconds) for when the run was created. + The type of the item. Always `program`. - - `expires_at: Integer` + - `:program` - The Unix timestamp (in seconds) for when the run will expire. + - `agent: Agent{ agent_name}` - - `failed_at: Integer` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run failed. + - `agent_name: String` - - `incomplete_details: IncompleteDetails{ 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. + - `class ProgramOutput` - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `id: 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 unique ID of the program output item. - - `:max_completion_tokens` + - `call_id: String` - - `:max_prompt_tokens` + The call ID of the program item. - - `instructions: String` + - `result: String` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The result produced by the program item. - - `last_error: LastError{ code, message}` + - `status: :completed | :incomplete` - The last error associated with this run. Will be `null` if there are no errors. + The terminal status of the program output item. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `:completed` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `:incomplete` - - `:server_error` + - `type: :program_output` - - `:rate_limit_exceeded` + The type of the item. Always `program_output`. - - `:invalid_prompt` + - `:program_output` - - `message: String` + - `agent: Agent{ agent_name}` - A human-readable description of the error. + The agent that produced this item. - - `max_completion_tokens: Integer` + - `agent_name: String` - The maximum number of completion tokens specified to have been used over the course of the run. + The canonical name of the agent that produced this item. - - `max_prompt_tokens: Integer` + - `class BetaResponseToolSearchCall` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `id: String` - - `metadata: Metadata` + The unique ID of the tool search call 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. + - `arguments: untyped` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Arguments used for the tool search call. - - `model: String` + - `call_id: String` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of the tool search call generated by the model. - - `object: :"thread.run"` + - `execution: :server | :client` - The object type, which is always `thread.run`. + Whether tool search was executed by the server or by the client. - - `:"thread.run"` + - `:server` - - `parallel_tool_calls: bool` + - `:client` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `status: :in_progress | :completed | :incomplete` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + The status of the tool search call item that was recorded. - Details on the action required to continue the run. Will be `null` if no action is required. + - `:in_progress` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + - `:completed` - Details on the tool outputs needed for this run to continue. + - `:incomplete` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + - `type: :tool_search_call` - A list of the relevant tool calls. + The type of the item. Always `tool_search_call`. - - `id: String` + - `:tool_search_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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `agent: Agent{ agent_name}` - - `function: Function{ arguments, name}` + The agent that produced this item. - The function definition. + - `agent_name: String` - - `arguments: String` + The canonical name of the agent that produced this item. - The arguments that the model expects you to pass to the function. + - `created_by: String` - - `name: String` + The identifier of the actor that created the item. - The name of the function. + - `class BetaResponseToolSearchOutputItem` - - `type: :function` + - `id: String` - The type of tool call the output is required for. For now, this is always `function`. + The unique ID of the tool search output item. - - `:function` + - `call_id: String` - - `type: :submit_tool_outputs` + The unique ID of the tool search call generated by the model. - For now, this is always `submit_tool_outputs`. + - `execution: :server | :client` - - `:submit_tool_outputs` + Whether tool search was executed by the server or by the client. - - `response_format: AssistantResponseFormatOption` + - `:server` - 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`. + - `:client` - 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). + - `status: :in_progress | :completed | :incomplete` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The status of the tool search output item that was recorded. - **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_progress` - - `AssistantResponseFormatOption = :auto` + - `:completed` - `auto` is the default value + - `:incomplete` - - `:auto` + - `tools: Array[BetaTool]` - - `class ResponseFormatText` + The loaded tool definitions returned by tool search. - Default response format. Used to generate text responses. + - `class BetaFunctionTool` - - `type: :text` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of response format being defined. Always `text`. + - `class BetaFileSearchTool` - - `: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). - - `class ResponseFormatJSONObject` + - `class BetaComputerTool` - 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 that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :json_object` + - `class BetaComputerUsePreviewTool` - The type of response format being defined. Always `json_object`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:json_object` + - `class BetaWebSearchTool` - - `class ResponseFormatJSONSchema` + 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](https://platform.openai.com/docs/guides/structured-outputs). + - `class Mcp` - - `json_schema: JSONSchema{ name, description, schema, strict}` + 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). - Structured Outputs configuration options, including a JSON Schema. + - `class CodeInterpreter` - - `name: String` + A tool that runs Python code to help generate a response to a prompt. - 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. + - `class ProgrammaticToolCalling` - - `description: String` + - `class ImageGeneration` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A tool that generates images using the GPT image models. - - `schema: Hash[Symbol, untyped]` + - `class LocalShell` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A tool that allows the model to execute shell commands in a local environment. - - `strict: bool` + - `class BetaFunctionShellTool` - 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). + A tool that allows the model to execute shell commands. - - `type: :json_schema` + - `class BetaCustomTool` - The type of response format being defined. Always `json_schema`. + 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) - - `:json_schema` + - `class BetaNamespaceTool` - - `started_at: Integer` + Groups function/custom tools under a shared namespace. - The Unix timestamp (in seconds) for when the run was started. + - `class BetaToolSearchTool` - - `status: untyped` + Hosted or BYOT tool search configuration for deferred tools. - - `thread_id: String` + - `class BetaWebSearchPreviewTool` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + 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). - - `tool_choice: AssistantToolChoiceOption` + - `class BetaApplyPatchTool` - 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. + Allows the assistant to create, delete, or update files using unified diffs. - - `Auto = :none | :auto | :required` + - `type: :tool_search_output` - `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 type of the item. Always `tool_search_output`. - - `:none` + - `:tool_search_output` - - `:auto` + - `agent: Agent{ agent_name}` - - `:required` + The agent that produced this item. - - `class AssistantToolChoice` + - `agent_name: String` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The canonical name of the agent that produced this item. - - `type: :function | :code_interpreter | :file_search` + - `created_by: String` - The type of the tool. If type is `function`, the function name must be set + The identifier of the actor that created the item. - - `:function` + - `class AdditionalTools` - - `:code_interpreter` + - `id: String` - - `:file_search` + The unique ID of the additional tools item. - - `function: AssistantToolChoiceFunction` + - `role: :unknown | :user | :assistant | 5 more` - - `name: String` + The role that provided the additional tools. - The name of the function to call. + - `:unknown` - - `tools: Array[untyped]` + - `:user` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `:assistant` - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + - `:system` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `:critic` - - `type: :auto | :last_messages` + - `:discriminator` - 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`. + - `:developer` - - `:auto` + - `:tool` - - `:last_messages` + - `tools: Array[BetaTool]` - - `last_messages: Integer` + The additional tool definitions made available at this item. - The number of most recent messages from the thread when constructing the context for the run. + - `class BetaFunctionTool` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + 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). - 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.). + - `class BetaFileSearchTool` - - `completion_tokens: Integer` + 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. + - `class BetaComputerTool` - - `prompt_tokens: Integer` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Number of prompt tokens used over the course of the run. + - `class BetaComputerUsePreviewTool` - - `total_tokens: Integer` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Total number of tokens used (prompt + completion). + - `class BetaWebSearchTool` - - `temperature: Float` + 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 sampling temperature used for this run. If not set, defaults to 1. + - `class Mcp` - - `top_p: Float` + 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 nucleus sampling value used for this run. If not set, defaults to 1. + - `class CodeInterpreter` -### Example + A tool that runs Python code to help generate a response to a prompt. -```ruby -require "openai" + - `class ProgrammaticToolCalling` -openai = OpenAI::Client.new(api_key: "My API Key") + - `class ImageGeneration` -run = openai.beta.threads.runs.submit_tool_outputs("run_id", thread_id: "thread_id", tool_outputs: [{}]) + A tool that generates images using the GPT image models. -puts(run) -``` + - `class LocalShell` -#### Response + A tool that allows the model to execute shell commands in a local environment. -```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": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `class BetaFunctionShellTool` -## Cancel a run + A tool that allows the model to execute shell commands. -`beta.threads.runs.cancel(run_id, **kwargs) -> Run` + - `class BetaCustomTool` -**post** `/threads/{thread_id}/runs/{run_id}/cancel` + 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) -Cancel a run + - `class BetaNamespaceTool` -### Parameters + Groups function/custom tools under a shared namespace. -- `thread_id: String` + - `class BetaToolSearchTool` -- `run_id: String` + Hosted or BYOT tool search configuration for deferred tools. -### Returns + - `class BetaWebSearchPreviewTool` -- `class Run` + 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). - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaApplyPatchTool` - - `id: String` + Allows the assistant to create, delete, or update files using unified diffs. - The identifier, which can be referenced in API endpoints. + - `type: :additional_tools` - - `assistant_id: String` + The type of the item. Always `additional_tools`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `:additional_tools` - - `cancelled_at: Integer` + - `agent: Agent{ agent_name}` - The Unix timestamp (in seconds) for when the run was cancelled. + The agent that produced this item. - - `completed_at: Integer` + - `agent_name: String` - The Unix timestamp (in seconds) for when the run was completed. + The canonical name of the agent that produced this item. - - `created_at: Integer` + - `class BetaResponseCompactionItem` - The Unix timestamp (in seconds) for when the run was created. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `expires_at: Integer` + - `id: String` - The Unix timestamp (in seconds) for when the run will expire. + The unique ID of the compaction item. - - `failed_at: Integer` + - `encrypted_content: String` - The Unix timestamp (in seconds) for when the run failed. + The encrypted content that was produced by compaction. - - `incomplete_details: IncompleteDetails{ reason}` + - `type: :compaction` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The type of the item. Always `compaction`. - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `:compaction` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `agent: Agent{ agent_name}` - - `:max_completion_tokens` + The agent that produced this item. - - `:max_prompt_tokens` + - `agent_name: String` - - `instructions: String` + The canonical name of the agent that produced this item. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `created_by: String` - - `last_error: LastError{ code, message}` + The identifier of the actor that created the item. - The last error associated with this run. Will be `null` if there are no errors. + - `class ImageGenerationCall` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + An image generation request made by the model. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `id: String` - - `:server_error` + The unique ID of the image generation call. - - `:rate_limit_exceeded` + - `result: String` - - `:invalid_prompt` + The generated image encoded in base64. - - `message: String` + - `status: :in_progress | :completed | :generating | :failed` - A human-readable description of the error. + The status of the image generation call. - - `max_completion_tokens: Integer` + - `:in_progress` - The maximum number of completion tokens specified to have been used over the course of the run. + - `:completed` - - `max_prompt_tokens: Integer` + - `:generating` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `:failed` - - `metadata: Metadata` + - `type: :image_generation_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. + The type of the image generation call. Always `image_generation_call`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:image_generation_call` - - `model: String` + - `agent: Agent{ agent_name}` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The agent that produced this item. - - `object: :"thread.run"` + - `agent_name: String` - The object type, which is always `thread.run`. + The canonical name of the agent that produced this item. - - `:"thread.run"` + - `class BetaResponseCodeInterpreterToolCall` - - `parallel_tool_calls: bool` + A tool call to run code. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `class LocalShellCall` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + A tool call to run a command on the local shell. - Details on the action required to continue the run. Will be `null` if no action is required. + - `id: String` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + The unique ID of the local shell call. - Details on the tool outputs needed for this run to continue. + - `action: Action{ command, env, type, 3 more}` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + Execute a shell command on the server. - A list of the relevant tool calls. + - `command: Array[String]` - - `id: String` + The command to run. - 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. + - `env: Hash[Symbol, String]` - - `function: Function{ arguments, name}` + Environment variables to set for the command. - The function definition. + - `type: :exec` - - `arguments: String` + The type of the local shell action. Always `exec`. - The arguments that the model expects you to pass to the function. + - `:exec` - - `name: String` + - `timeout_ms: Integer` - The name of the function. + Optional timeout in milliseconds for the command. - - `type: :function` + - `user: String` - The type of tool call the output is required for. For now, this is always `function`. + Optional user to run the command as. - - `:function` + - `working_directory: String` - - `type: :submit_tool_outputs` + Optional working directory to run the command in. - For now, this is always `submit_tool_outputs`. + - `call_id: String` - - `:submit_tool_outputs` + The unique ID of the local shell tool call generated by the model. - - `response_format: AssistantResponseFormatOption` + - `status: :in_progress | :completed | :incomplete` - 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 status of the local shell 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). + - `:in_progress` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `:completed` - **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. + - `:incomplete` - - `AssistantResponseFormatOption = :auto` + - `type: :local_shell_call` - `auto` is the default value + The type of the local shell call. Always `local_shell_call`. - - `:auto` + - `:local_shell_call` - - `class ResponseFormatText` + - `agent: Agent{ agent_name}` - Default response format. Used to generate text responses. + The agent that produced this item. - - `type: :text` + - `agent_name: String` - The type of response format being defined. Always `text`. + The canonical name of the agent that produced this item. - - `:text` + - `class LocalShellCallOutput` - - `class ResponseFormatJSONObject` + The output of a local shell 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. + - `id: String` - - `type: :json_object` + The unique ID of the local shell tool call generated by the model. - The type of response format being defined. Always `json_object`. + - `output: String` - - `:json_object` + A JSON string of the output of the local shell tool call. - - `class ResponseFormatJSONSchema` + - `type: :local_shell_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). + The type of the local shell tool call output. Always `local_shell_call_output`. - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `:local_shell_call_output` - Structured Outputs configuration options, including a JSON Schema. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `agent_name: String` - - `description: String` + The canonical name of the agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `status: :in_progress | :completed | :incomplete` - - `schema: Hash[Symbol, untyped]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `:in_progress` - - `strict: bool` + - `:completed` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `:incomplete` - - `type: :json_schema` + - `class BetaResponseFunctionShellToolCall` - The type of response format being defined. Always `json_schema`. + A tool call that executes one or more shell commands in a managed environment. - - `:json_schema` + - `id: String` - - `started_at: Integer` + The unique ID of the shell tool call. Populated when this item is returned via API. - The Unix timestamp (in seconds) for when the run was started. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `status: untyped` + The shell commands and limits that describe how to run the tool call. - - `thread_id: String` + - `commands: Array[String]` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `max_output_length: Integer` - - `tool_choice: AssistantToolChoiceOption` + Optional maximum number of characters to return from each command. - 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. + - `timeout_ms: Integer` - - `Auto = :none | :auto | :required` + Optional timeout in milliseconds for the commands. - `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. + - `call_id: String` - - `:none` + The unique ID of the shell tool call generated by the model. - - `:auto` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:required` + Represents the use of a local environment to perform shell actions. - - `class AssistantToolChoice` + - `class BetaResponseLocalEnvironment` - Specifies a tool the model should use. Use to force the model to call a specific tool. + Represents the use of a local environment to perform shell actions. - - `type: :function | :code_interpreter | :file_search` + - `type: :local` - The type of the tool. If type is `function`, the function name must be set + The environment type. Always `local`. - - `:function` + - `:local` - - `:code_interpreter` + - `class BetaResponseContainerReference` - - `:file_search` + Represents a container created with /v1/containers. - - `function: AssistantToolChoiceFunction` + - `container_id: String` - - `name: String` + - `type: :container_reference` - The name of the function to call. + The environment type. Always `container_reference`. - - `tools: Array[untyped]` + - `:container_reference` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `status: :in_progress | :completed | :incomplete` - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `:in_progress` - - `type: :auto | :last_messages` + - `:completed` - 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`. + - `:incomplete` - - `:auto` + - `type: :shell_call` - - `:last_messages` + The type of the item. Always `shell_call`. - - `last_messages: Integer` + - `:shell_call` - The number of most recent messages from the thread when constructing the context for the run. + - `agent: Agent{ agent_name}` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + 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.). + - `agent_name: String` - - `completion_tokens: Integer` + The canonical name of the agent that produced this item. - Number of completion tokens used over the course of the run. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `prompt_tokens: Integer` + The execution context that produced this tool call. - Number of prompt tokens used over the course of the run. + - `class Direct` - - `total_tokens: Integer` + - `type: :direct` - Total number of tokens used (prompt + completion). + - `:direct` - - `temperature: Float` + - `class Program` - The sampling temperature used for this run. If not set, defaults to 1. + - `caller_id: String` - - `top_p: Float` + The call ID of the program item that produced this tool call. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: :program` -### Example + - `:program` -```ruby -require "openai" + - `created_by: String` -openai = OpenAI::Client.new(api_key: "My API Key") + The ID of the entity that created this tool call. -run = openai.beta.threads.runs.cancel("run_id", thread_id: "thread_id") + - `class BetaResponseFunctionShellToolCallOutput` -puts(run) -``` + The output of a shell tool call that was emitted. -#### Response + - `id: String` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The unique ID of the shell call output. Populated when this item is returned via API. -## Domain Types + - `call_id: String` -### Required Action Function Tool Call + The unique ID of the shell tool call generated by the model. -- `class RequiredActionFunctionToolCall` + - `max_output_length: Integer` - Tool call objects + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `id: String` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - 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. + An array of shell call output contents - - `function: Function{ arguments, name}` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The function definition. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `arguments: String` + - `class Timeout` - The arguments that the model expects you to pass to the function. + Indicates that the shell call exceeded its configured time limit. - - `name: String` + - `type: :timeout` - The name of the function. + The outcome type. Always `timeout`. - - `type: :function` + - `:timeout` - The type of tool call the output is required for. For now, this is always `function`. + - `class Exit` - - `:function` + Indicates that the shell commands finished and returned an exit code. -### Run + - `exit_code: Integer` -- `class Run` + Exit code from the shell process. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: :exit` - - `id: String` + The outcome type. Always `exit`. - The identifier, which can be referenced in API endpoints. + - `:exit` - - `assistant_id: String` + - `stderr: String` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The standard error output that was captured. - - `cancelled_at: Integer` + - `stdout: String` - The Unix timestamp (in seconds) for when the run was cancelled. + The standard output that was captured. - - `completed_at: Integer` + - `created_by: String` - The Unix timestamp (in seconds) for when the run was completed. + The identifier of the actor that created the item. - - `created_at: Integer` + - `status: :in_progress | :completed | :incomplete` - The Unix timestamp (in seconds) for when the run was created. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `expires_at: Integer` + - `:in_progress` - The Unix timestamp (in seconds) for when the run will expire. + - `:completed` - - `failed_at: Integer` + - `:incomplete` - The Unix timestamp (in seconds) for when the run failed. + - `type: :shell_call_output` - - `incomplete_details: IncompleteDetails{ reason}` + The type of the shell call output. Always `shell_call_output`. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `:shell_call_output` - - `reason: :max_completion_tokens | :max_prompt_tokens` + - `agent: Agent{ agent_name}` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The agent that produced this item. - - `:max_completion_tokens` + - `agent_name: String` - - `:max_prompt_tokens` + The canonical name of the agent that produced this item. - - `instructions: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The execution context that produced this tool call. - - `last_error: LastError{ code, message}` + - `class Direct` - The last error associated with this run. Will be `null` if there are no errors. + - `type: :direct` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` + - `:direct` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `class Program` - - `:server_error` + - `caller_id: String` - - `:rate_limit_exceeded` + The call ID of the program item that produced this tool call. - - `:invalid_prompt` + - `type: :program` - - `message: String` + - `:program` - A human-readable description of the error. + - `created_by: String` - - `max_completion_tokens: Integer` + The identifier of the actor that created the item. - The maximum number of completion tokens specified to have been used over the course of the run. + - `class BetaResponseApplyPatchToolCall` - - `max_prompt_tokens: Integer` + A tool call that applies file diffs by creating, deleting, or updating files. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `id: String` - - `metadata: Metadata` + The unique ID of the apply patch tool call. Populated when this item is 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. + - `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 apply patch tool call generated by the model. - - `model: String` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `object: :"thread.run"` + - `class CreateFile` - The object type, which is always `thread.run`. + Instruction describing how to create a file via the apply_patch tool. - - `:"thread.run"` + - `diff: String` - - `parallel_tool_calls: bool` + Diff to apply. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `path: String` - - `required_action: RequiredAction{ submit_tool_outputs, type}` + Path of the file to create. - Details on the action required to continue the run. Will be `null` if no action is required. + - `type: :create_file` - - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` + Create a new file with the provided diff. - Details on the tool outputs needed for this run to continue. + - `:create_file` - - `tool_calls: Array[RequiredActionFunctionToolCall]` + - `class DeleteFile` - A list of the relevant tool calls. + Instruction describing how to delete a file via the apply_patch tool. - - `id: String` + - `path: 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. + Path of the file to delete. - - `function: Function{ arguments, name}` + - `type: :delete_file` - The function definition. + Delete the specified file. - - `arguments: String` + - `:delete_file` - The arguments that the model expects you to pass to the function. + - `class UpdateFile` - - `name: String` + Instruction describing how to update a file via the apply_patch tool. - The name of the function. + - `diff: String` - - `type: :function` + Diff to apply. - The type of tool call the output is required for. For now, this is always `function`. + - `path: String` - - `:function` + Path of the file to update. - - `type: :submit_tool_outputs` + - `type: :update_file` - For now, this is always `submit_tool_outputs`. + Update an existing file with the provided diff. - - `:submit_tool_outputs` + - `:update_file` - - `response_format: AssistantResponseFormatOption` + - `status: :in_progress | :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`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - 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). + - `:in_progress` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `:completed` - **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. + - `type: :apply_patch_call` - - `AssistantResponseFormatOption = :auto` + The type of the item. Always `apply_patch_call`. - `auto` is the default value + - `:apply_patch_call` - - `:auto` + - `agent: Agent{ agent_name}` - - `class ResponseFormatText` + The agent that produced this item. - Default response format. Used to generate text responses. + - `agent_name: String` - - `type: :text` + The canonical name of the agent that produced this item. - The type of response format being defined. Always `text`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:text` + The execution context that produced this tool call. - - `class ResponseFormatJSONObject` + - `class 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. + - `type: :direct` - - `type: :json_object` + - `:direct` - The type of response format being defined. Always `json_object`. + - `class Program` - - `:json_object` + - `caller_id: String` - - `class ResponseFormatJSONSchema` + 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` - - `json_schema: JSONSchema{ name, description, schema, strict}` + - `:program` - Structured Outputs configuration options, including a JSON Schema. + - `created_by: String` - - `name: String` + The ID of the entity that created this 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. + - `class BetaResponseApplyPatchToolCallOutput` - - `description: String` + The output emitted by an apply patch tool call. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `id: String` - - `schema: Hash[Symbol, untyped]` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `call_id: String` - - `strict: bool` + The unique ID of the apply patch tool call generated by the model. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `status: :completed | :failed` - - `type: :json_schema` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of response format being defined. Always `json_schema`. + - `:completed` - - `:json_schema` + - `:failed` - - `started_at: Integer` + - `type: :apply_patch_call_output` - The Unix timestamp (in seconds) for when the run was started. + The type of the item. Always `apply_patch_call_output`. - - `status: untyped` + - `:apply_patch_call_output` - - `thread_id: String` + - `agent: Agent{ agent_name}` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The agent that produced this item. - - `tool_choice: AssistantToolChoiceOption` + - `agent_name: 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 canonical name of the agent that produced this item. - - `Auto = :none | :auto | :required` + - `caller_: Direct{ type} | Program{ caller_id, 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. + The execution context that produced this tool call. - - `:none` + - `class Direct` - - `:auto` + - `type: :direct` - - `:required` + - `:direct` - - `class AssistantToolChoice` + - `class Program` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `caller_id: String` - - `type: :function | :code_interpreter | :file_search` + The call ID of the program item that produced this tool call. - The type of the tool. If type is `function`, the function name must be set + - `type: :program` - - `:function` + - `:program` - - `:code_interpreter` + - `created_by: String` - - `:file_search` + The ID of the entity that created this tool call output. - - `function: AssistantToolChoiceFunction` + - `output: String` - - `name: String` + Optional textual output returned by the apply patch tool. - The name of the function to call. + - `class McpCall` - - `tools: Array[untyped]` + An invocation of a tool on an MCP server. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `id: String` - - `truncation_strategy: TruncationStrategy{ type, last_messages}` + The unique ID of the tool call. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `arguments: String` - - `type: :auto | :last_messages` + A JSON string of the arguments passed to the tool. - 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`. + - `name: String` - - `:auto` + The name of the tool that was run. - - `:last_messages` + - `server_label: String` - - `last_messages: Integer` + The label of the MCP server running the tool. - The number of most recent messages from the thread when constructing the context for the run. + - `type: :mcp_call` - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + The type of the item. Always `mcp_call`. - 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.). + - `:mcp_call` - - `completion_tokens: Integer` + - `agent: Agent{ agent_name}` - Number of completion tokens used over the course of the run. + The agent that produced this item. - - `prompt_tokens: Integer` + - `agent_name: String` - Number of prompt tokens used over the course of the run. + The canonical name of the agent that produced this item. - - `total_tokens: Integer` + - `approval_request_id: String` - Total number of tokens used (prompt + completion). + 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. - - `temperature: Float` + - `error: String` - The sampling temperature used for this run. If not set, defaults to 1. + The error from the tool call, if any. - - `top_p: Float` + - `output: String` - The nucleus sampling value used for this run. If not set, defaults to 1. + The output from the tool call. -### Run Status + - `status: :in_progress | :completed | :incomplete | 2 more` -- `RunStatus = untyped` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. -# Steps + - `:in_progress` -## List run steps + - `:completed` -`beta.threads.runs.steps.list(run_id, **kwargs) -> CursorPage` + - `:incomplete` -**get** `/threads/{thread_id}/runs/{run_id}/steps` + - `:calling` -List run steps + - `:failed` -### Parameters + - `class McpListTools` -- `thread_id: String` + A list of tools available on an MCP server. -- `run_id: String` + - `id: String` -- `after: String` + The unique ID of the list. - 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. + - `server_label: String` -- `before: String` + The label of the MCP server. - 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. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` -- `include: Array[RunStepInclude]` + The tools available on the server. - 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. + - `input_schema: untyped` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The JSON schema describing the tool's input. - - `:"step_details.tool_calls[*].file_search.results[*].content"` + - `name: String` -- `limit: Integer` + The name of the tool. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `annotations: untyped` -- `order: :asc | :desc` + Additional annotations about the tool. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `description: String` - - `:asc` + The description of the tool. - - `:desc` + - `type: :mcp_list_tools` -### Returns + The type of the item. Always `mcp_list_tools`. -- `class RunStep` + - `:mcp_list_tools` - Represents a step in execution of a run. + - `agent: Agent{ agent_name}` - - `id: String` + The agent that produced this item. - The identifier of the run step, which can be referenced in API endpoints. + - `agent_name: String` - - `assistant_id: String` + The canonical name of the agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `error: String` - - `cancelled_at: Integer` + Error message if the server could not list tools. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `class McpApprovalRequest` - - `completed_at: Integer` + A request for human approval of a tool invocation. - The Unix timestamp (in seconds) for when the run step completed. + - `id: String` - - `created_at: Integer` + The unique ID of the approval request. - The Unix timestamp (in seconds) for when the run step was created. + - `arguments: String` - - `expired_at: Integer` + A JSON string of arguments for the tool. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `name: String` - - `failed_at: Integer` + The name of the tool to run. - The Unix timestamp (in seconds) for when the run step failed. + - `server_label: String` - - `last_error: LastError{ code, message}` + The label of the MCP server making the request. - The last error associated with this run step. Will be `null` if there are no errors. + - `type: :mcp_approval_request` - - `code: :server_error | :rate_limit_exceeded` + The type of the item. Always `mcp_approval_request`. - One of `server_error` or `rate_limit_exceeded`. + - `:mcp_approval_request` - - `:server_error` + - `agent: Agent{ agent_name}` - - `:rate_limit_exceeded` + 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. - - `metadata: Metadata` + - `class McpApprovalResponse` - Set of 16 key-value pairs that can be attached to an object. 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 response to an MCP approval request. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: String` - - `object: :"thread.run.step"` + The unique ID of the approval response - The object type, which is always `thread.run.step`. + - `approval_request_id: String` - - `:"thread.run.step"` + The ID of the approval request being answered. - - `run_id: String` + - `approve: bool` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + Whether the request was approved. - - `status: :in_progress | :cancelled | :failed | 2 more` + - `type: :mcp_approval_response` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The type of the item. Always `mcp_approval_response`. - - `:in_progress` + - `:mcp_approval_response` - - `:cancelled` + - `agent: Agent{ agent_name}` - - `:failed` + The agent that produced this item. - - `:completed` + - `agent_name: String` - - `:expired` + The canonical name of the agent that produced this item. - - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` + - `reason: String` - The details of the run step. + Optional reason for the decision. - - `class MessageCreationStepDetails` + - `class BetaResponseCustomToolCall` - Details of the message creation by the run step. + A call to a custom tool created by the model. - - `message_creation: MessageCreation{ message_id}` + - `class BetaResponseCustomToolCallOutputItem` - - `message_id: String` + The output of a custom tool call from your code, being sent back to the model. - The ID of the message that was created by this run step. + - `id: String` - - `type: :message_creation` + The unique ID of the custom tool call output item. - Always `message_creation`. + - `status: :in_progress | :completed | :incomplete` - - `:message_creation` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class ToolCallsStepDetails` + - `:in_progress` - Details of the tool call. + - `:completed` - - `tool_calls: Array[untyped]` + - `: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`. + - `created_by: String` - - `type: :tool_calls` + The identifier of the actor that created the item. - Always `tool_calls`. + - `parallel_tool_calls: bool` - - `:tool_calls` + Whether to allow the model to run tool calls in parallel. - - `thread_id: String` + - `temperature: Float` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `type: :message_creation | :tool_calls` + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - The type of run step, which can be either `message_creation` or `tool_calls`. + 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. - - `:message_creation` + - `BetaToolChoiceOptions = :none | :auto | :required` - - `:tool_calls` + Controls which (if any) tool is called by the model. - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + `none` means the model will not call any tool and instead generates a message. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `completion_tokens: Integer` + `required` means the model must call one or more tools. - Number of completion tokens used over the course of the run step. + - `:none` - - `prompt_tokens: Integer` + - `:auto` - Number of prompt tokens used over the course of the run step. + - `:required` - - `total_tokens: Integer` + - `class BetaToolChoiceAllowed` - Total number of tokens used (prompt + completion). + Constrains the tools available to the model to a pre-defined set. -### Example + - `mode: :auto | :required` -```ruby -require "openai" + Constrains the tools available to the model to a pre-defined set. -openai = OpenAI::Client.new(api_key: "My API Key") + `auto` allows the model to pick from among the allowed tools and generate a + message. -page = openai.beta.threads.runs.steps.list("run_id", thread_id: "thread_id") + `required` requires the model to call one or more of the allowed tools. -puts(page) -``` + - `:auto` -#### Response + - `:required` -```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" -} -``` + - `tools: Array[Hash[Symbol, untyped]]` -## Retrieve run step + A list of tool definitions that the model should be allowed to call. -`beta.threads.runs.steps.retrieve(step_id, **kwargs) -> RunStep` + For the Responses API, the list of tool definitions might look like: -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` -Retrieve run step + - `type: :allowed_tools` -### Parameters + Allowed tool configuration type. Always `allowed_tools`. -- `thread_id: String` + - `:allowed_tools` -- `run_id: String` + - `class BetaToolChoiceTypes` -- `step_id: 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). -- `include: Array[RunStepInclude]` + - `type: :file_search | :web_search_preview | :computer | 5 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 type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Allowed values are: - - `:"step_details.tool_calls[*].file_search.results[*].content"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` -### Returns + - `:file_search` -- `class RunStep` + - `:web_search_preview` - Represents a step in execution of a run. + - `:computer` - - `id: String` + - `:computer_use_preview` - The identifier of the run step, which can be referenced in API endpoints. + - `:computer_use` - - `assistant_id: String` + - `:web_search_preview_2025_03_11` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `:image_generation` - - `cancelled_at: Integer` + - `:code_interpreter` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `class BetaToolChoiceFunction` - - `completed_at: Integer` + Use this option to force the model to call a specific function. - The Unix timestamp (in seconds) for when the run step completed. + - `name: String` - - `created_at: Integer` + The name of the function to call. - The Unix timestamp (in seconds) for when the run step was created. + - `type: :function` - - `expired_at: Integer` + For function calling, the type is always `function`. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `:function` - - `failed_at: Integer` + - `class BetaToolChoiceMcp` - The Unix timestamp (in seconds) for when the run step failed. + Use this option to force the model to call a specific tool on a remote MCP server. - - `last_error: LastError{ code, message}` + - `server_label: String` - The last error associated with this run step. Will be `null` if there are no errors. + The label of the MCP server to use. - - `code: :server_error | :rate_limit_exceeded` + - `type: :mcp` - One of `server_error` or `rate_limit_exceeded`. + For MCP tools, the type is always `mcp`. - - `:server_error` + - `:mcp` - - `:rate_limit_exceeded` + - `name: String` - - `message: String` + The name of the tool to call on the server. - A human-readable description of the error. + - `class BetaToolChoiceCustom` - - `metadata: Metadata` + Use this option to force the model to call a specific custom tool. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `name: String` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the custom tool to call. - - `object: :"thread.run.step"` + - `type: :custom` - The object type, which is always `thread.run.step`. + For custom tool calling, the type is always `custom`. - - `:"thread.run.step"` + - `:custom` - - `run_id: String` + - `class BetaSpecificProgrammaticToolCallingParam` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `type: :programmatic_tool_calling` - - `status: :in_progress | :cancelled | :failed | 2 more` + The tool to call. Always `programmatic_tool_calling`. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `:programmatic_tool_calling` - - `:in_progress` + - `class BetaToolChoiceApplyPatch` - - `:cancelled` + Forces the model to call the apply_patch tool when executing a tool call. - - `:failed` + - `type: :apply_patch` - - `:completed` + The tool to call. Always `apply_patch`. - - `:expired` + - `:apply_patch` - - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` + - `class BetaToolChoiceShell` - The details of the run step. + Forces the model to call the shell tool when a tool call is required. - - `class MessageCreationStepDetails` + - `type: :shell` - Details of the message creation by the run step. + The tool to call. Always `shell`. - - `message_creation: MessageCreation{ message_id}` + - `:shell` - - `message_id: String` + - `tools: Array[BetaTool]` - The ID of the message that was created by this run step. + 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: :message_creation` + We support the following categories of tools: - Always `message_creation`. + - **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. - - `:message_creation` + - `class BetaFunctionTool` - - `class ToolCallsStepDetails` + 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). - Details of the tool call. + - `class BetaFileSearchTool` - - `tool_calls: Array[untyped]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - An 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`. + - `class BetaComputerTool` - - `type: :tool_calls` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Always `tool_calls`. + - `class BetaComputerUsePreviewTool` - - `:tool_calls` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `thread_id: String` + - `class BetaWebSearchTool` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + 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: :message_creation | :tool_calls` + - `class Mcp` - The type of run step, which can be either `message_creation` or `tool_calls`. + 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_creation` + - `class CodeInterpreter` - - `:tool_calls` + A tool that runs Python code to help generate a response to a prompt. - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `class ProgrammaticToolCalling` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `class ImageGeneration` - - `completion_tokens: Integer` + A tool that generates images using the GPT image models. - Number of completion tokens used over the course of the run step. + - `class LocalShell` - - `prompt_tokens: Integer` + A tool that allows the model to execute shell commands in a local environment. - Number of prompt tokens used over the course of the run step. + - `class BetaFunctionShellTool` - - `total_tokens: Integer` + A tool that allows the model to execute shell commands. - Total number of tokens used (prompt + completion). + - `class BetaCustomTool` -### Example + 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) -```ruby -require "openai" + - `class BetaNamespaceTool` -openai = OpenAI::Client.new(api_key: "My API Key") + Groups function/custom tools under a shared namespace. -run_step = openai.beta.threads.runs.steps.retrieve("step_id", thread_id: "thread_id", run_id: "run_id") + - `class BetaToolSearchTool` -puts(run_step) -``` + Hosted or BYOT tool search configuration for deferred tools. -#### Response + - `class BetaWebSearchPreviewTool` -```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 - } -} -``` + 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). -## Domain Types + - `class BetaApplyPatchTool` -### Code Interpreter Logs + Allows the assistant to create, delete, or update files using unified diffs. -- `class CodeInterpreterLogs` + - `top_p: Float` - Text output from the Code Interpreter tool call as part of a run step. + 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. - - `index: Integer` + We generally recommend altering this or `temperature` but not both. - The index of the output in the outputs array. + - `background: bool` - - `type: :logs` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - Always `logs`. + - `completed_at: Float` - - `:logs` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `logs: String` + - `conversation: Conversation{ id}` - The text output from the Code Interpreter tool call. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. -### Code Interpreter Output Image + - `id: String` -- `class CodeInterpreterOutputImage` + The unique ID of the conversation that this response was associated with. - - `index: Integer` + - `max_output_tokens: Integer` - The index of the output in the outputs array. + 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: :image` + - `max_tool_calls: Integer` - Always `image`. + 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. - - `:image` + - `moderation: Moderation{ input, output}` - - `image: Image{ file_id}` + Moderation results for the response input and output, if moderated completions were requested. - - `file_id: String` + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + Moderation for the response input. -### Code Interpreter Tool Call + - `class ModerationResult` -- `class CodeInterpreterToolCall` + A moderation result produced for the response input or output. - Details of the Code Interpreter tool call the run step was involved in. + - `categories: Hash[Symbol, bool]` - - `id: String` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The ID of the tool call. + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `code_interpreter: CodeInterpreter{ input, outputs}` + Which modalities of input are reflected by the score for each category. - The Code Interpreter tool call definition. + - `:text` - - `input: String` + - `:image` - The input to the Code Interpreter tool call. + - `category_scores: Hash[Symbol, Float]` - - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` + A dictionary of moderation categories to scores. - 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. + - `flagged: bool` - - `class Logs` + A boolean indicating whether the content was flagged by any category. - Text output from the Code Interpreter tool call as part of a run step. + - `model: String` - - `logs: String` + The moderation model that produced this result. - The text output from the Code Interpreter tool call. + - `type: :moderation_result` - - `type: :logs` + The object type, which was always `moderation_result` for successful moderation results. - Always `logs`. + - `:moderation_result` - - `:logs` + - `class Error` - - `class Image` + An error produced while attempting moderation for the response input or output. - - `image: Image{ file_id}` + - `code: String` - - `file_id: String` + The error code. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `message: String` - - `type: :image` + The error message. - Always `image`. + - `type: :error` - - `:image` + The object type, which was always `error` for moderation failures. - - `type: :code_interpreter` + - `:error` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `:code_interpreter` + Moderation for the response output. -### Code Interpreter Tool Call Delta + - `class ModerationResult` -- `class CodeInterpreterToolCallDelta` + A moderation result produced for the response input or output. - Details of the Code Interpreter tool call the run step was involved in. + - `categories: Hash[Symbol, bool]` - - `index: Integer` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The index of the tool call in the tool calls array. + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `type: :code_interpreter` + Which modalities of input are reflected by the score for each category. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `:text` - - `:code_interpreter` + - `:image` - - `id: String` + - `category_scores: Hash[Symbol, Float]` - The ID of the tool call. + A dictionary of moderation categories to scores. - - `code_interpreter: CodeInterpreter{ input, outputs}` + - `flagged: bool` - The Code Interpreter tool call definition. + A boolean indicating whether the content was flagged by any category. - - `input: String` + - `model: String` - The input to the Code Interpreter tool call. + The moderation model that produced this result. - - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` + - `type: :moderation_result` - 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 object type, which was always `moderation_result` for successful moderation results. - - `class CodeInterpreterLogs` + - `:moderation_result` - Text output from the Code Interpreter tool call as part of a run step. + - `class Error` - - `index: Integer` + An error produced while attempting moderation for the response input or output. - The index of the output in the outputs array. + - `code: String` - - `type: :logs` + The error code. - Always `logs`. + - `message: String` - - `:logs` + The error message. - - `logs: String` + - `type: :error` - The text output from the Code Interpreter tool call. + The object type, which was always `error` for moderation failures. - - `class CodeInterpreterOutputImage` + - `:error` - - `index: Integer` + - `previous_response_id: String` - The index of the output in the outputs array. + 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: :image` + - `prompt: BetaResponsePrompt` - Always `image`. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `:image` + - `id: String` - - `image: Image{ file_id}` + The unique identifier of the prompt template to use. - - `file_id: String` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the 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. -### File Search Tool Call + - `String = String` -- `class FileSearchToolCall` + - `class BetaResponseInputText` - - `id: String` + A text input to the model. - The ID of the tool call object. + - `class BetaResponseInputImage` - - `file_search: FileSearch{ ranking_options, results}` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - For now, this is always going to be an empty object. + - `class BetaResponseInputFile` - - `ranking_options: RankingOptions{ ranker, score_threshold}` + A file input to the model. - The ranking options for the file search. + - `version: String` - - `ranker: :auto | :default_2024_08_21` + Optional version of the prompt template. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `prompt_cache_key: String` - - `:auto` + 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). - - `:default_2024_08_21` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `score_threshold: Float` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `mode: :implicit | :explicit` - - `results: Array[Result{ file_id, file_name, score, content}]` + Whether implicit prompt-cache breakpoints were enabled. - The results of the file search. + - `:implicit` - - `file_id: String` + - `:explicit` - The ID of the file that result was found in. + - `ttl: :"30m"` - - `file_name: String` + The minimum lifetime applied to each cache breakpoint. - The name of the file that result was found in. + - `:"30m"` - - `score: Float` + - `prompt_cache_retention: :in_memory | :"24h"` - The score of the result. All values must be a floating point number between 0 and 1. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `content: Array[Content{ text, type}]` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](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 content of the result that was found. The content is only included if requested via the include query parameter. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `text: String` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The text content of the file. + - `:in_memory` - - `type: :text` + - `:"24h"` - The type of the content. + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - - `:text` + **gpt-5 and o-series models only** - - `type: :file_search` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `context: :auto | :current_turn | :all_turns` - - `:file_search` + 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: :none | :minimal | :low | 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: :auto | :concise | :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: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + + - `summary: :auto | :concise | :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: 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). + + - `service_tier: :auto | :default | :flex | 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](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'. + + 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: 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: 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_: 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. + + - `class Text` + + Default response format. Used to generate text responses. + + - `type: :text` + + The type of response format being defined. Always `text`. + + - `:text` + + - `class BetaResponseFormatTextJSONSchemaConfig` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/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: Hash[Symbol, untyped]` + + 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: String` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: bool` + + 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). + + - `class JSONObject` + + 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: :low | :medium | :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: Integer` + + 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: :auto | :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: BetaResponseUsage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: Integer` + + The number of input tokens. + + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + + - `cached_tokens: Integer` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: Integer` + + The number of output tokens. + + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: Integer` + + The number of reasoning tokens. + + - `total_tokens: Integer` + + The total number of tokens used. + + - `user: 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). + +### Example + +```ruby +require "openai" + +openai = OpenAI::Client.new(api_key: "My API Key") + +beta_response = openai.beta.responses.create + +puts(beta_response) +``` + +#### 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" + } + ], + "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" +} +``` + +## Get a model response + +`beta.responses.retrieve(response_id, **kwargs) -> BetaResponse` + +**get** `/responses/{response_id}?beta=true` + +Retrieves a model response with the given ID. + +### Parameters + +- `response_id: String` + +- `include: Array[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: bool` + + 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: Integer` + + The sequence number of the event after which to start streaming. + +- `stream: bool` + + 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. + +- `betas: Array[:"responses_multi_agent=v1"]` + + - `:"responses_multi_agent=v1"` + +### Returns + +- `class BetaResponse` + + - `id: String` + + Unique identifier for this Response. + + - `created_at: Float` + + 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 | :rate_limit_exceeded | :invalid_prompt | 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: IncompleteDetails{ reason}` + + Details about why the response is incomplete. + + - `reason: :max_output_tokens | :content_filter` + + The reason why the response is incomplete. + + - `:max_output_tokens` + + - `:content_filter` + + - `instructions: String | Array[BetaResponseInputItem]` + + 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 = String` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `InputItemList = Array[BetaResponseInputItem]` + + A list of one or many input items to the model, containing + different content types. + + - `class BetaEasyInputMessage` + + 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 | BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String = String` + + A text input to the model. + + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 | :assistant | :system | :developer` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `:user` + + - `:assistant` + + - `:system` + + - `:developer` + + - `phase: :commentary | :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: :message` + + The type of the message input. Always `message`. + + - `:message` + + - `class Message` + + 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 | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + 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. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + 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: Integer` + + 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` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `: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: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :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` + + - `class BetaResponseFileSearchToolCall` + + 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[String]` + + The queries used to search for files. + + - `status: :in_progress | :searching | :completed | 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. 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 = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `file_id: String` + + The unique ID of the file. + + - `filename: String` + + The name of the file. + + - `score: Float` + + The relevance score of the file - a value between 0 and 1. + + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + 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[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :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: BetaComputerAction` + + A click action. + + - `class Click` + + A click action. + + - `button: :left | :right | :wheel | 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: Integer` + + The x-coordinate where the click occurred. + + - `y_: Integer` + + The y-coordinate where the click occurred. + + - `keys: Array[String]` + + The keys being held while clicking. + + - `class DoubleClick` + + A double click action. + + - `keys: Array[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: Integer` + + The x-coordinate where the double click occurred. + + - `y_: Integer` + + The y-coordinate where the double click occurred. + + - `class Drag` + + A drag action. + + - `path: Array[Path{ 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: Integer` + + The x-coordinate. + + - `y_: Integer` + + The y-coordinate. + + - `type: :drag` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `:drag` + + - `keys: Array[String]` + + The keys being held while dragging the mouse. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `keys: Array[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` + + - `class Move` + + A mouse move action. + + - `type: :move` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `:move` + + - `x: Integer` + + The x-coordinate to move to. + + - `y_: Integer` + + The y-coordinate to move to. + + - `keys: Array[String]` + + The keys being held while moving the mouse. + + - `class Screenshot` + + A screenshot action. + + - `type: :screenshot` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `:screenshot` + + - `class Scroll` + + A scroll action. + + - `scroll_x: Integer` + + The horizontal scroll distance. + + - `scroll_y: Integer` + + The vertical scroll distance. + + - `type: :scroll` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class 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` + + - `class Wait` + + A wait action. + + - `type: :wait` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `:wait` + + - `actions: BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click` + + A click action. + + - `class DoubleClick` + + A double click action. + + - `class Drag` + + A drag action. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `class Move` + + A mouse move action. + + - `class Screenshot` + + A screenshot action. + + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ComputerCallOutput` + + 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: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: 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: String` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ 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: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :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` + + - `class BetaResponseFunctionWebSearch` + + 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: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). + + - `class Search` + + Action type "search" - Performs a web search query. + + - `type: :search` + + The action type. + + - `:search` + + - `queries: Array[String]` + + The search queries. + + - `query: String` + + The search query. + + - `sources: Array[Source{ type, url}]` + + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` + + - `url: String` + + The URL of the source. + + - `class OpenPage` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: :open_page` + + The action type. + + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + 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 | :searching | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/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: String` + + The unique ID of the function tool call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the function to run. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class FunctionCallOutput` + + The output of a function tool call. + + - `call_id: String` + + The unique ID of the function tool call generated by the model. + + - `output: String | BetaResponseFunctionCallOutputItemList` + + Text, image, or file output of the function tool call. + + - `String = String` + + A JSON string of the output of the function tool call. + + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + + An array of content outputs (text, image, file) for the function tool call. + + - `class BetaResponseInputTextContent` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImageContent` + + 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`. + + - `:input_image` + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFileContent` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: String` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class AgentMessage` + + A message routed between agents. + + - `author: String` + + The sending agent identity. + + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent` + + 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: String` + + The unique ID of this agent message item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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: String` + + The unique ID of this multi-agent call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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[Output{ 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: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + Citations associated with the text content. + + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The citation type. Always `file_citation`. + + - `:file_citation` + + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + + - `end_index: Integer` + + The index of the last character of the citation in the message. + + - `start_index: Integer` + + 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. + + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + - `container_id: String` + + The ID of the container. + + - `end_index: Integer` + + 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: Integer` + + 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: String` + + The unique ID of this multi-agent call output. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ToolSearchCall` + + - `arguments: untyped` + + The arguments supplied to the tool search call. + + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` + + - `id: String` + + The unique ID of this tool search call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search call. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseToolSearchOutputItemParam` + + - `tools: Array[BetaTool]` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool` + + 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: Hash[Symbol, untyped]` + + A JSON schema object describing the parameters of the function. + + - `strict: bool` + + Whether strict parameter validation is enforced for this function tool. + + - `type: :function` + + The type of the function tool. Always `function`. + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function is deferred and loaded via tool search. + + - `description: String` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool` + + 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[String]` + + The IDs of the vector stores to search. + + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + + A filter to apply. + + - `class ComparisonFilter` + + 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 | :ne | :gt | 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 | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `class CompoundFilter` + + Combine multiple filters using `and` or `or`. + + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class ComparisonFilter` + + 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 | :ne | :gt | 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 | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `UnionMember1 = untyped` + + - `type: :and | :or` + + Type of operation: `and` or `or`. + + - `:and` + + - `:or` + + - `max_num_results: Integer` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + + Ranking options for search. + + - `hybrid_search: HybridSearch{ 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: Float` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: Float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: :auto | :"default-2024-11-15"` + + The ranker to use for the file search. + + - `:auto` + + - `:"default-2024-11-15"` + + - `score_threshold: Float` + + 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. + + - `class BetaComputerTool` + + 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` + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: Integer` + + The height of the computer display. + + - `display_width: Integer` + + The width of the computer display. + + - `environment: :windows | :mac | :linux | 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` + + - `class BetaWebSearchTool` + + 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 | :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: Filters{ allowed_domains}` + + Filters for the search. + + - `allowed_domains: Array[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: :low | :medium | :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: UserLocation{ city, country, region, 2 more}` + + The approximate location of the user. + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `class Mcp` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = Array[String]` + + A string array of allowed tool names + + - `class McpToolFilter` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `authorization: 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: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 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: bool` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Hash[Symbol, String]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter` + + 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: Always{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `never: Never{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `McpToolApprovalSetting = :always | :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: String` + + Optional description of the MCP server, used to provide more context. + + - `server_url: String` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_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. + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: String | CodeInterpreterToolAuto{ 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 = String` + + The container ID. + + - `class CodeInterpreterToolAuto` + + 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: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the code interpreter container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `type: :disabled` + + Disable outbound network access. Always `disabled`. + + - `:disabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `allowed_domains: Array[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: Array[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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + + - `class ImageGeneration` + + 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: :generate | :edit | :auto` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `:generate` + + - `:edit` + + - `:auto` + + - `background: :transparent | :opaque | :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: :high | :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: InputImageMask{ file_id, image_url}` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: String` + + File ID for the mask image. + + - `image_url: String` + + Base64-encoded mask image. + + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `String = String` + + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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: :auto | :low` + + Moderation level for the generated image. Default: `auto`. + + - `:auto` + + - `:low` + + - `output_compression: Integer` + + Compression level for the output image. Default: 100. + + - `output_format: :png | :webp | :jpeg` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `:png` + + - `:webp` + + - `:jpeg` + + - `partial_images: Integer` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: :low | :medium | :high | :auto` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `:low` + + - `:medium` + + - `:high` + + - `:auto` + + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 = String` + + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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` + + - `class LocalShell` + + 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` + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `type: :shell` + + The type of the shell tool. Always `shell`. + + - `:shell` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + + - `class BetaContainerAuto` + + - `type: :container_auto` + + Automatically creates a container for this request + + - `:container_auto` + + - `file_ids: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `skills: Array[BetaSkillReference | BetaInlineSkill]` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference` + + - `skill_id: String` + + The ID of the referenced skill. + + - `type: :skill_reference` + + References a skill created with the /v1/skills endpoint. + + - `:skill_reference` + + - `version: String` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill` + + - `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` + + - `class BetaLocalEnvironment` + + - `type: :local` + + Use a local computer environment. + + - `:local` + + - `skills: Array[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. + + - `class BetaContainerReference` + + - `container_id: String` + + The ID of the referenced container. + + - `type: :container_reference` + + References a container created with the /v1/containers endpoint + + - `:container_reference` + + - `class BetaCustomTool` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this tool should be deferred and discovered via tool search. + + - `description: String` + + Optional description of the custom tool, used to provide more context. + + - `format_: Text{ type} | Grammar{ definition, syntax, type}` + + The input format for the custom tool. Default is unconstrained text. + + - `class Text` + + Unconstrained free-form text. + + - `type: :text` + + Unconstrained text format. Always `text`. + + - `:text` + + - `class Grammar` + + A grammar defined by the user. + + - `definition: String` + + The grammar definition. + + - `syntax: :lark | :regex` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `:lark` + + - `:regex` + + - `type: :grammar` + + Grammar format. Always `grammar`. + + - `:grammar` + + - `class BetaNamespaceTool` + + 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[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + + The function/custom tools available inside this namespace. + + - `class Function` + + - `name: String` + + - `type: :function` + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function should be deferred and discovered via tool search. + + - `description: String` + + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: untyped` + + - `strict: bool` + + 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. + + - `class BetaCustomTool` + + 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: :namespace` + + The type of the tool. Always `namespace`. + + - `:namespace` + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: :tool_search` + + The type of the tool. Always `tool_search`. + + - `:tool_search` + + - `description: String` + + Description shown to the model for a client-executed tool search tool. + + - `execution: :server | :client` + + Whether tool search is executed by the server or by the client. + + - `:server` + + - `:client` + + - `parameters: untyped` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool` + + 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 | :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: Array[:text | :image]` + + - `:text` + + - `:image` + + - `search_context_size: :low | :medium | :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: UserLocation{ type, city, country, 2 more}` + + The user's location. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `type: :tool_search_output` + + The item type. Always `tool_search_output`. + + - `:tool_search_output` + + - `id: String` + + The unique ID of this tool search output. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class AdditionalTools` + + - `role: :developer` + + The role that provided the additional tools. Only `developer` is supported. + + - `:developer` + + - `tools: Array[BetaTool]` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The item type. Always `additional_tools`. + + - `:additional_tools` + + - `id: String` + + The unique ID of this additional tools item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem` + + 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[Summary{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ 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: String` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseCompactionItemParam` + + 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: String` + + The ID of the compaction item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ImageGenerationCall` + + 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 | :completed | :generating | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall` + + 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[Logs{ logs, type} | Image{ type, url}]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class Logs` + + 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` + + - `class Image` + + 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 | :completed | :incomplete | 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCall` + + A tool call to run a command on the local shell. + + - `id: String` + + The unique ID of the local shell call. + + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` + + The command to run. + + - `env: Hash[Symbol, String]` + + Environment variables to set for the command. + + - `type: :exec` + + The type of the local shell action. Always `exec`. + + - `:exec` + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the command. + + - `user: String` + + Optional user to run the command as. + + - `working_directory: 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCall` + + A tool representing a request to execute one or more shell commands. + + - `action: Action{ commands, max_output_length, timeout_ms}` + + The shell commands and limits that describe how to run the tool call. + + - `commands: Array[String]` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: Integer` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: Integer` + + 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: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `environment: BetaLocalEnvironment | BetaContainerReference` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment` + + - `class BetaContainerReference` + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCallOutput` + + 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[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Timeout{ type} | Exit{ exit_code, type}` + + The exit or timeout outcome associated with this shell call. + + - `class Timeout` + + Indicates that the shell call exceeded its configured time limit. + + - `type: :timeout` + + The outcome type. Always `timeout`. + + - `:timeout` + + - `class Exit` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: Integer` + + 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: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `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: Integer` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call output. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ApplyPatchCall` + + 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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class CreateFile` + + 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` + + - `class DeleteFile` + + 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` + + - `class UpdateFile` + + 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 | :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: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class ApplyPatchCallOutput` + + 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 | :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: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `output: String` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools` + + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class McpCall` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_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. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class BetaResponseCustomToolCallOutput` + + 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + 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: String` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + 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: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. + + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 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"` + + - `:"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 = String` + + - `object: :response` + + The object type of this resource - always set to `response`. + + - `:response` + + - `output: Array[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. + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall` + + 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. + + - `class BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem` + + - `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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the function call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the function call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `status: :in_progress | :completed | :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 function tool call output. Always `function_call_output`. + + - `:function_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `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: String` + + The identifier of the actor that created the item. + + - `class AgentMessage` + + - `id: String` + + The unique ID of the agent message. + + - `author: String` + + The sending agent identity. + + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + + Encrypted content sent between agents. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `class Text` + + A text content. + + - `text: String` + + - `type: :text` + + - `:text` + + - `class SummaryText` + + 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` + + - `class ReasoningText` + + 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` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot` + + A screenshot of a computer. + + - `detail: :low | :high | :auto | :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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `class EncryptedContent` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` + + - `id: String` + + The unique ID of the multi-agent call item. + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput` + + - `id: String` + + The unique ID of the multi-agent call output item. + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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[BetaResponseOutputText]` + + Text output returned by the multi-agent action. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ 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: Array[Logprob{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionWebSearch` + + 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. + + - `class BetaResponseComputerToolCall` + + 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. + + - `class BetaResponseComputerToolCallOutputItem` + + - `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 | :incomplete | :failed | :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: Array[AcknowledgedSafetyCheck{ 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: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem` + + 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). + + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall` + + - `id: String` + + The unique ID of the tool search call item. + + - `arguments: untyped` + + Arguments used for the tool search call. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` + + - `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 | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output item that was recorded. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `tools: Array[BetaTool]` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :tool_search_output` + + The type of the item. Always `tool_search_output`. + + - `:tool_search_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class AdditionalTools` + + - `id: String` + + The unique ID of the additional tools item. + + - `role: :unknown | :user | :assistant | 5 more` + + The role that provided the additional tools. + + - `:unknown` + + - `:user` + + - `:assistant` + + - `:system` + + - `:critic` + + - `:discriminator` + + - `:developer` + + - `:tool` + + - `tools: Array[BetaTool]` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The type of the item. Always `additional_tools`. + + - `:additional_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: String` + + The unique ID of the compaction item. + + - `encrypted_content: String` + + The encrypted content that was produced by compaction. + + - `type: :compaction` + + The type of the item. Always `compaction`. + + - `:compaction` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class ImageGenerationCall` + + 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 | :completed | :generating | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall` + + A tool call to run code. + + - `class LocalShellCall` + + A tool call to run a command on the local shell. + + - `id: String` + + The unique ID of the local shell call. + + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` + + The command to run. + + - `env: Hash[Symbol, String]` + + Environment variables to set for the command. + + - `type: :exec` + + The type of the local shell action. Always `exec`. + + - `:exec` + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the command. + + - `user: String` + + Optional user to run the command as. + + - `working_directory: 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseFunctionShellToolCall` + + 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: Action{ commands, max_output_length, timeout_ms}` + + The shell commands and limits that describe how to run the tool call. + + - `commands: Array[String]` + + - `max_output_length: Integer` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the commands. + + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment` + + Represents the use of a local environment to perform shell actions. + + - `type: :local` + + The environment type. Always `local`. + + - `:local` + + - `class BetaResponseContainerReference` + + Represents a container created with /v1/containers. + + - `container_id: String` + + - `type: :container_reference` + + The environment type. Always `container_reference`. + + - `:container_reference` + + - `status: :in_progress | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput` + + 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: Integer` + + 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[Output{ outcome, stderr, stdout, created_by}]` + + An array of shell call output contents + + - `outcome: Timeout{ type} | Exit{ exit_code, type}` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `class Timeout` + + Indicates that the shell call exceeded its configured time limit. + + - `type: :timeout` + + The outcome type. Always `timeout`. + + - `:timeout` + + - `class Exit` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: Integer` + + 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: String` + + The identifier of the actor that created the item. + + - `status: :in_progress | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall` + + 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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class CreateFile` + + 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` + + - `class DeleteFile` + + 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` + + - `class UpdateFile` + + 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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + 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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call output. + + - `output: String` + + Optional textual output returned by the apply patch tool. + + - `class McpCall` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_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. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class McpListTools` + + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + 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: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: String` + + The unique ID of the custom tool call output item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: bool` + + Whether to allow the model to run tool calls in parallel. + + - `temperature: Float` + + 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 | BetaToolChoiceAllowed | BetaToolChoiceTypes | 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 | :auto | :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` + + - `class BetaToolChoiceAllowed` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: :auto | :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[Hash[Symbol, untyped]]` + + 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` + + - `class BetaToolChoiceTypes` + + 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 | :web_search_preview | :computer | 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` + + - `class BetaToolChoiceFunction` + + 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` + + - `class BetaToolChoiceMcp` + + 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: String` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom` + + 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` + + - `class BetaSpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + + - `class BetaToolChoiceApplyPatch` + + 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` + + - `class BetaToolChoiceShell` + + 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[BetaTool]` + + 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. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_p: Float` + + 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: bool` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: Float` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: Conversation{ 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: Integer` + + 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: Integer` + + 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: Moderation{ input, output}` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + + Moderation for the response input. + + - `class ModerationResult` + + A moderation result produced for the response input or output. + + - `categories: Hash[Symbol, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + + Which modalities of input are reflected by the score for each category. + + - `:text` + + - `:image` + + - `category_scores: Hash[Symbol, Float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + 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` + + - `class Error` + + 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: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + + Moderation for the response output. + + - `class ModerationResult` + + A moderation result produced for the response input or output. + + - `categories: Hash[Symbol, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + + Which modalities of input are reflected by the score for each category. + + - `:text` + + - `:image` + + - `category_scores: Hash[Symbol, Float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + 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` + + - `class Error` + + 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: 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: 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: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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 = String` + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `version: String` + + Optional version of the prompt template. + + - `prompt_cache_key: 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: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + + - `prompt_cache_retention: :in_memory | :"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: Reasoning{ 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: :auto | :current_turn | :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: :none | :minimal | :low | 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: :auto | :concise | :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: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + + - `summary: :auto | :concise | :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: 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). + + - `service_tier: :auto | :default | :flex | 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](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'. + + 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: 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: 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_: 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. + + - `class Text` + + Default response format. Used to generate text responses. + + - `type: :text` + + The type of response format being defined. Always `text`. + + - `:text` + + - `class BetaResponseFormatTextJSONSchemaConfig` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/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: Hash[Symbol, untyped]` + + 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: String` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: bool` + + 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). + + - `class JSONObject` + + 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: :low | :medium | :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: Integer` + + 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: :auto | :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: BetaResponseUsage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: Integer` + + The number of input tokens. + + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + + - `cached_tokens: Integer` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: Integer` + + The number of output tokens. + + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: Integer` + + The number of reasoning tokens. + + - `total_tokens: Integer` + + The total number of tokens used. + + - `user: 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). + +### Example + +```ruby +require "openai" + +openai = OpenAI::Client.new(api_key: "My API Key") + +beta_response = openai.beta.responses.retrieve("resp_677efb5139a88190b512bc3fef8e535d") + +puts(beta_response) +``` + +#### 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" + } + ], + "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" +} +``` + +## Delete a model response + +`beta.responses.delete(response_id, **kwargs) -> void` + +**delete** `/responses/{response_id}?beta=true` + +Deletes a model response with the given ID. + +### Parameters + +- `response_id: String` + +- `betas: Array[:"responses_multi_agent=v1"]` + + - `:"responses_multi_agent=v1"` + +### Example + +```ruby +require "openai" + +openai = OpenAI::Client.new(api_key: "My API Key") + +result = openai.beta.responses.delete("resp_677efb5139a88190b512bc3fef8e535d") + +puts(result) +``` + +## Cancel a response + +`beta.responses.cancel(response_id, **kwargs) -> BetaResponse` + +**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](https://platform.openai.com/docs/guides/background). + +### Parameters + +- `response_id: String` + +- `betas: Array[:"responses_multi_agent=v1"]` + + - `:"responses_multi_agent=v1"` + +### Returns + +- `class BetaResponse` + + - `id: String` + + Unique identifier for this Response. + + - `created_at: Float` + + 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 | :rate_limit_exceeded | :invalid_prompt | 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: IncompleteDetails{ reason}` + + Details about why the response is incomplete. + + - `reason: :max_output_tokens | :content_filter` + + The reason why the response is incomplete. + + - `:max_output_tokens` + + - `:content_filter` + + - `instructions: String | Array[BetaResponseInputItem]` + + 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 = String` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `InputItemList = Array[BetaResponseInputItem]` + + A list of one or many input items to the model, containing + different content types. + + - `class BetaEasyInputMessage` + + 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 | BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String = String` + + A text input to the model. + + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 | :assistant | :system | :developer` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `:user` + + - `:assistant` + + - `:system` + + - `:developer` + + - `phase: :commentary | :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: :message` + + The type of the message input. Always `message`. + + - `:message` + + - `class Message` + + 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 | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + 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. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + 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: Integer` + + 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` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `: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: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :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` + + - `class BetaResponseFileSearchToolCall` + + 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[String]` + + The queries used to search for files. + + - `status: :in_progress | :searching | :completed | 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. 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 = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `file_id: String` + + The unique ID of the file. + + - `filename: String` + + The name of the file. + + - `score: Float` + + The relevance score of the file - a value between 0 and 1. + + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + 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[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :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: BetaComputerAction` + + A click action. + + - `class Click` + + A click action. + + - `button: :left | :right | :wheel | 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: Integer` + + The x-coordinate where the click occurred. + + - `y_: Integer` + + The y-coordinate where the click occurred. + + - `keys: Array[String]` + + The keys being held while clicking. + + - `class DoubleClick` + + A double click action. + + - `keys: Array[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: Integer` + + The x-coordinate where the double click occurred. + + - `y_: Integer` + + The y-coordinate where the double click occurred. + + - `class Drag` + + A drag action. + + - `path: Array[Path{ 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: Integer` + + The x-coordinate. + + - `y_: Integer` + + The y-coordinate. + + - `type: :drag` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `:drag` + + - `keys: Array[String]` + + The keys being held while dragging the mouse. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `keys: Array[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` + + - `class Move` + + A mouse move action. + + - `type: :move` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `:move` + + - `x: Integer` + + The x-coordinate to move to. + + - `y_: Integer` + + The y-coordinate to move to. + + - `keys: Array[String]` + + The keys being held while moving the mouse. + + - `class Screenshot` + + A screenshot action. + + - `type: :screenshot` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `:screenshot` + + - `class Scroll` + + A scroll action. + + - `scroll_x: Integer` + + The horizontal scroll distance. + + - `scroll_y: Integer` + + The vertical scroll distance. + + - `type: :scroll` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class 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` + + - `class Wait` + + A wait action. + + - `type: :wait` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `:wait` + + - `actions: BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click` + + A click action. + + - `class DoubleClick` + + A double click action. + + - `class Drag` + + A drag action. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `class Move` + + A mouse move action. + + - `class Screenshot` + + A screenshot action. + + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ComputerCallOutput` + + 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: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: 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: String` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ 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: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :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` + + - `class BetaResponseFunctionWebSearch` + + 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: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). + + - `class Search` + + Action type "search" - Performs a web search query. + + - `type: :search` + + The action type. + + - `:search` + + - `queries: Array[String]` + + The search queries. + + - `query: String` + + The search query. + + - `sources: Array[Source{ type, url}]` + + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` + + - `url: String` + + The URL of the source. + + - `class OpenPage` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: :open_page` + + The action type. + + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + 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 | :searching | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/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: String` + + The unique ID of the function tool call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the function to run. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class FunctionCallOutput` + + The output of a function tool call. + + - `call_id: String` + + The unique ID of the function tool call generated by the model. + + - `output: String | BetaResponseFunctionCallOutputItemList` + + Text, image, or file output of the function tool call. + + - `String = String` + + A JSON string of the output of the function tool call. + + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + + An array of content outputs (text, image, file) for the function tool call. + + - `class BetaResponseInputTextContent` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImageContent` + + 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`. + + - `:input_image` + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFileContent` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: String` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class AgentMessage` + + A message routed between agents. + + - `author: String` + + The sending agent identity. + + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent` + + 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: String` + + The unique ID of this agent message item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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: String` + + The unique ID of this multi-agent call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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[Output{ 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: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + Citations associated with the text content. + + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The citation type. Always `file_citation`. + + - `:file_citation` + + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + + - `end_index: Integer` + + The index of the last character of the citation in the message. + + - `start_index: Integer` + + 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. + + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + - `container_id: String` + + The ID of the container. + + - `end_index: Integer` + + 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: Integer` + + 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: String` + + The unique ID of this multi-agent call output. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ToolSearchCall` + + - `arguments: untyped` + + The arguments supplied to the tool search call. + + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` + + - `id: String` + + The unique ID of this tool search call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search call. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseToolSearchOutputItemParam` + + - `tools: Array[BetaTool]` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool` + + 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: Hash[Symbol, untyped]` + + A JSON schema object describing the parameters of the function. + + - `strict: bool` + + Whether strict parameter validation is enforced for this function tool. + + - `type: :function` + + The type of the function tool. Always `function`. + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function is deferred and loaded via tool search. + + - `description: String` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool` + + 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[String]` + + The IDs of the vector stores to search. + + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + + A filter to apply. + + - `class ComparisonFilter` + + 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 | :ne | :gt | 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 | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `class CompoundFilter` + + Combine multiple filters using `and` or `or`. + + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class ComparisonFilter` + + 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 | :ne | :gt | 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 | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `UnionMember1 = untyped` + + - `type: :and | :or` + + Type of operation: `and` or `or`. + + - `:and` + + - `:or` + + - `max_num_results: Integer` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + + Ranking options for search. + + - `hybrid_search: HybridSearch{ 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: Float` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: Float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: :auto | :"default-2024-11-15"` + + The ranker to use for the file search. + + - `:auto` + + - `:"default-2024-11-15"` + + - `score_threshold: Float` + + 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. + + - `class BetaComputerTool` + + 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` + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: Integer` + + The height of the computer display. + + - `display_width: Integer` + + The width of the computer display. + + - `environment: :windows | :mac | :linux | 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` + + - `class BetaWebSearchTool` + + 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 | :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: Filters{ allowed_domains}` + + Filters for the search. + + - `allowed_domains: Array[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: :low | :medium | :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: UserLocation{ city, country, region, 2 more}` + + The approximate location of the user. + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `class Mcp` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = Array[String]` + + A string array of allowed tool names + + - `class McpToolFilter` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `authorization: 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: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 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: bool` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Hash[Symbol, String]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter` + + 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: Always{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `never: Never{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `McpToolApprovalSetting = :always | :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: String` + + Optional description of the MCP server, used to provide more context. + + - `server_url: String` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_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. + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: String | CodeInterpreterToolAuto{ 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 = String` + + The container ID. + + - `class CodeInterpreterToolAuto` + + 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: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the code interpreter container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `type: :disabled` + + Disable outbound network access. Always `disabled`. + + - `:disabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `allowed_domains: Array[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: Array[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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + + - `class ImageGeneration` + + 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: :generate | :edit | :auto` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `:generate` + + - `:edit` + + - `:auto` + + - `background: :transparent | :opaque | :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: :high | :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: InputImageMask{ file_id, image_url}` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: String` + + File ID for the mask image. + + - `image_url: String` + + Base64-encoded mask image. + + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `String = String` + + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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: :auto | :low` + + Moderation level for the generated image. Default: `auto`. + + - `:auto` + + - `:low` + + - `output_compression: Integer` + + Compression level for the output image. Default: 100. + + - `output_format: :png | :webp | :jpeg` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `:png` + + - `:webp` + + - `:jpeg` + + - `partial_images: Integer` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: :low | :medium | :high | :auto` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `:low` + + - `:medium` + + - `:high` + + - `:auto` + + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 = String` + + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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` + + - `class LocalShell` + + 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` + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `type: :shell` + + The type of the shell tool. Always `shell`. + + - `:shell` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + + - `class BetaContainerAuto` + + - `type: :container_auto` + + Automatically creates a container for this request + + - `:container_auto` + + - `file_ids: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `skills: Array[BetaSkillReference | BetaInlineSkill]` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference` + + - `skill_id: String` + + The ID of the referenced skill. + + - `type: :skill_reference` + + References a skill created with the /v1/skills endpoint. + + - `:skill_reference` + + - `version: String` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill` + + - `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` + + - `class BetaLocalEnvironment` + + - `type: :local` + + Use a local computer environment. + + - `:local` + + - `skills: Array[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. + + - `class BetaContainerReference` + + - `container_id: String` + + The ID of the referenced container. + + - `type: :container_reference` + + References a container created with the /v1/containers endpoint + + - `:container_reference` + + - `class BetaCustomTool` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this tool should be deferred and discovered via tool search. + + - `description: String` + + Optional description of the custom tool, used to provide more context. + + - `format_: Text{ type} | Grammar{ definition, syntax, type}` + + The input format for the custom tool. Default is unconstrained text. + + - `class Text` + + Unconstrained free-form text. + + - `type: :text` + + Unconstrained text format. Always `text`. + + - `:text` + + - `class Grammar` + + A grammar defined by the user. + + - `definition: String` + + The grammar definition. + + - `syntax: :lark | :regex` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `:lark` + + - `:regex` + + - `type: :grammar` + + Grammar format. Always `grammar`. + + - `:grammar` + + - `class BetaNamespaceTool` + + 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[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + + The function/custom tools available inside this namespace. + + - `class Function` + + - `name: String` + + - `type: :function` + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function should be deferred and discovered via tool search. + + - `description: String` + + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: untyped` + + - `strict: bool` + + 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. + + - `class BetaCustomTool` + + 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: :namespace` + + The type of the tool. Always `namespace`. + + - `:namespace` + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: :tool_search` + + The type of the tool. Always `tool_search`. + + - `:tool_search` + + - `description: String` + + Description shown to the model for a client-executed tool search tool. + + - `execution: :server | :client` + + Whether tool search is executed by the server or by the client. + + - `:server` + + - `:client` + + - `parameters: untyped` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool` + + 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 | :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: Array[:text | :image]` + + - `:text` + + - `:image` + + - `search_context_size: :low | :medium | :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: UserLocation{ type, city, country, 2 more}` + + The user's location. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `type: :tool_search_output` + + The item type. Always `tool_search_output`. + + - `:tool_search_output` + + - `id: String` + + The unique ID of this tool search output. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class AdditionalTools` + + - `role: :developer` + + The role that provided the additional tools. Only `developer` is supported. + + - `:developer` + + - `tools: Array[BetaTool]` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The item type. Always `additional_tools`. + + - `:additional_tools` + + - `id: String` + + The unique ID of this additional tools item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem` + + 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[Summary{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ 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: String` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseCompactionItemParam` + + 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: String` + + The ID of the compaction item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ImageGenerationCall` + + 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 | :completed | :generating | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall` + + 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[Logs{ logs, type} | Image{ type, url}]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class Logs` + + 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` + + - `class Image` + + 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 | :completed | :incomplete | 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCall` + + A tool call to run a command on the local shell. + + - `id: String` + + The unique ID of the local shell call. + + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` + + The command to run. + + - `env: Hash[Symbol, String]` + + Environment variables to set for the command. + + - `type: :exec` + + The type of the local shell action. Always `exec`. + + - `:exec` + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the command. + + - `user: String` + + Optional user to run the command as. + + - `working_directory: 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCall` + + A tool representing a request to execute one or more shell commands. + + - `action: Action{ commands, max_output_length, timeout_ms}` + + The shell commands and limits that describe how to run the tool call. + + - `commands: Array[String]` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: Integer` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: Integer` + + 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: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `environment: BetaLocalEnvironment | BetaContainerReference` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment` + + - `class BetaContainerReference` + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCallOutput` + + 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[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Timeout{ type} | Exit{ exit_code, type}` + + The exit or timeout outcome associated with this shell call. + + - `class Timeout` + + Indicates that the shell call exceeded its configured time limit. + + - `type: :timeout` + + The outcome type. Always `timeout`. + + - `:timeout` + + - `class Exit` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: Integer` + + 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: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `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: Integer` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call output. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ApplyPatchCall` + + 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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class CreateFile` + + 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` + + - `class DeleteFile` + + 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` + + - `class UpdateFile` + + 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 | :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: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class ApplyPatchCallOutput` + + 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 | :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: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `output: String` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools` + + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class McpCall` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_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. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class BetaResponseCustomToolCallOutput` + + 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + 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: String` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + 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: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. + + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 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"` -### File Search Tool Call Delta + - `:"gpt-5.4-mini"` -- `class FileSearchToolCallDelta` + - `:"gpt-5.4-nano"` - - `file_search: untyped` + - `:"gpt-5.4-mini-2026-03-17"` - For now, this is always going to be an empty object. + - `:"gpt-5.4-nano-2026-03-17"` - - `index: Integer` + - `:"gpt-5.3-chat-latest"` - The index of the tool call in the tool calls array. + - `:"gpt-5.2"` - - `type: :file_search` + - `:"gpt-5.2-2025-12-11"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `:"gpt-5.2-chat-latest"` - - `:file_search` + - `:"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"` + + - `:"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 = String` + + - `object: :response` + + The object type of this resource - always set to `response`. + + - `:response` + + - `output: Array[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. + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall` + + 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. + + - `class BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem` - `id: String` - The ID of the tool call object. + The unique ID of the function call tool output. -### Function Tool Call + - `call_id: String` -- `class FunctionToolCall` + The unique ID of the function tool call generated by the model. + + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the function call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the function call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `status: :in_progress | :completed | :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 function tool call output. Always `function_call_output`. + + - `:function_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `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: String` + + The identifier of the actor that created the item. + + - `class AgentMessage` - `id: String` - The ID of the tool call object. + The unique ID of the agent message. - - `function: Function{ arguments, name, output}` + - `author: String` - The definition of the function that was called. + The sending agent identity. - - `arguments: String` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - The arguments passed to the function. + Encrypted content sent between agents. - - `name: String` + - `class BetaResponseInputText` - The name of the function. + A text input to the model. - - `output: String` + - `class BetaResponseOutputText` - 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. + A text output from the model. - - `type: :function` + - `class Text` - The type of tool call. This is always going to be `function` for this type of tool call. + A text content. - - `:function` + - `text: String` -### Function Tool Call Delta + - `type: :text` -- `class FunctionToolCallDelta` + - `:text` - - `index: Integer` + - `class SummaryText` - The index of the tool call in the tool calls array. + A summary text from the model. - - `type: :function` + - `text: String` - The type of tool call. This is always going to be `function` for this type of tool call. + A summary of the reasoning output from the model so far. - - `:function` + - `type: :summary_text` + + The type of the object. Always `summary_text`. + + - `:summary_text` + + - `class ReasoningText` + + 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` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot` + + A screenshot of a computer. + + - `detail: :low | :high | :auto | :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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `class EncryptedContent` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` - `id: String` - The ID of the tool call object. + The unique ID of the multi-agent call item. - - `function: Function{ arguments, name, output}` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The definition of the function that was called. + The multi-agent action to execute. + + - `:spawn_agent` + + - `:interrupt_agent` + + - `:list_agents` + + - `:send_message` + + - `:followup_task` + + - `:wait_agent` - `arguments: String` - The arguments passed to the function. + The JSON string of arguments generated for the action. - - `name: String` + - `call_id: String` - The name of the function. + The unique ID linking this call to its output. - - `output: String` + - `type: :multi_agent_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. + The type of the multi-agent call. Always `multi_agent_call`. -### Message Creation Step Details + - `:multi_agent_call` -- `class MessageCreationStepDetails` + - `agent: Agent{ agent_name}` - Details of the message creation by the run step. + The agent that produced this item. - - `message_creation: MessageCreation{ message_id}` + - `agent_name: String` - - `message_id: String` + The canonical name of the agent that produced this item. - The ID of the message that was created by this run step. + - `class MultiAgentCallOutput` - - `type: :message_creation` + - `id: String` - Always `message_creation`. + The unique ID of the multi-agent call output item. - - `:message_creation` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` -### Run Step + The multi-agent action that produced this result. -- `class RunStep` + - `:spawn_agent` - Represents a step in execution of a run. + - `:interrupt_agent` + + - `:list_agents` + + - `:send_message` + + - `:followup_task` + + - `:wait_agent` + + - `call_id: String` + + The unique ID of the multi-agent call. + + - `output: Array[BetaResponseOutputText]` + + Text output returned by the multi-agent action. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ 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: Array[Logprob{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionWebSearch` + + 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. + + - `class BetaResponseComputerToolCall` + + 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. + + - `class BetaResponseComputerToolCallOutputItem` - `id: String` - The identifier of the run step, which can be referenced in API endpoints. + The unique ID of the computer call tool output. - - `assistant_id: String` + - `call_id: String` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The ID of the computer tool call that produced the output. - - `cancelled_at: Integer` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The Unix timestamp (in seconds) for when the run step was cancelled. + A computer screenshot image used with the computer use tool. - - `completed_at: Integer` + - `status: :completed | :incomplete | :failed | :in_progress` - The Unix timestamp (in seconds) for when the run step completed. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `created_at: Integer` + - `:completed` - The Unix timestamp (in seconds) for when the run step was created. + - `:incomplete` - - `expired_at: Integer` + - `:failed` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `:in_progress` - - `failed_at: Integer` + - `type: :computer_call_output` - The Unix timestamp (in seconds) for when the run step failed. + The type of the computer tool call output. Always `computer_call_output`. - - `last_error: LastError{ code, message}` + - `:computer_call_output` - The last error associated with this run step. Will be `null` if there are no errors. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `code: :server_error | :rate_limit_exceeded` + The safety checks reported by the API that have been acknowledged by the + developer. - One of `server_error` or `rate_limit_exceeded`. + - `id: String` - - `:server_error` + The ID of the pending safety check. - - `:rate_limit_exceeded` + - `code: String` + + The type of the pending safety check. - `message: String` - A human-readable description of the error. + Details about the pending safety check. - - `metadata: Metadata` + - `agent: Agent{ agent_name}` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `agent_name: String` - - `object: :"thread.run.step"` + The canonical name of the agent that produced this item. - The object type, which is always `thread.run.step`. + - `created_by: String` - - `:"thread.run.step"` + The identifier of the actor that created the item. - - `run_id: String` + - `class BetaResponseReasoningItem` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + 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). - - `status: :in_progress | :cancelled | :failed | 2 more` + - `class Program` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall` + + - `id: String` + + The unique ID of the tool search call item. + + - `arguments: untyped` + + Arguments used for the tool search call. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search call item that was recorded. - `:in_progress` - - `:cancelled` + - `:completed` - - `:failed` + - `:incomplete` + + - `type: :tool_search_call` + + The type of the item. Always `tool_search_call`. + + - `:tool_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` + + - `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 | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output item that was recorded. + + - `:in_progress` - `:completed` - - `:expired` + - `:incomplete` - - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` + - `tools: Array[BetaTool]` - The details of the run step. + The loaded tool definitions returned by tool search. - - `class MessageCreationStepDetails` + - `class BetaFunctionTool` - Details of the message creation by the run step. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `message_creation: MessageCreation{ message_id}` + - `class BetaFileSearchTool` - - `message_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 message that was created by this run step. + - `class BetaComputerTool` - - `type: :message_creation` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Always `message_creation`. + - `class BetaComputerUsePreviewTool` - - `:message_creation` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class ToolCallsStepDetails` + - `class BetaWebSearchTool` - Details of 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). - - `tool_calls: Array[untyped]` + - `class Mcp` - 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`. + 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: :tool_calls` + - `class CodeInterpreter` - Always `tool_calls`. + A tool that runs Python code to help generate a response to a prompt. - - `:tool_calls` + - `class ProgrammaticToolCalling` - - `thread_id: String` + - `class ImageGeneration` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + A tool that generates images using the GPT image models. - - `type: :message_creation | :tool_calls` + - `class LocalShell` - The type of run step, which can be either `message_creation` or `tool_calls`. + A tool that allows the model to execute shell commands in a local environment. - - `:message_creation` + - `class BetaFunctionShellTool` - - `:tool_calls` + A tool that allows the model to execute shell commands. - - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` + - `class BetaCustomTool` - Usage statistics related to the run step. This value will be `null` while the run step's status is `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) - - `completion_tokens: Integer` + - `class BetaNamespaceTool` - Number of completion tokens used over the course of the run step. + Groups function/custom tools under a shared namespace. - - `prompt_tokens: Integer` + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :tool_search_output` + + The type of the item. Always `tool_search_output`. + + - `:tool_search_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class AdditionalTools` + + - `id: String` + + The unique ID of the additional tools item. + + - `role: :unknown | :user | :assistant | 5 more` + + The role that provided the additional tools. + + - `:unknown` + + - `:user` + + - `:assistant` + + - `:system` + + - `:critic` + + - `:discriminator` + + - `:developer` + + - `:tool` + + - `tools: Array[BetaTool]` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The type of the item. Always `additional_tools`. + + - `:additional_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: String` + + The unique ID of the compaction item. + + - `encrypted_content: String` + + The encrypted content that was produced by compaction. + + - `type: :compaction` + + The type of the item. Always `compaction`. + + - `:compaction` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class ImageGenerationCall` + + 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 | :completed | :generating | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall` - Number of prompt tokens used over the course of the run step. + A tool call to run code. - - `total_tokens: Integer` + - `class LocalShellCall` - Total number of tokens used (prompt + completion). + A tool call to run a command on the local shell. -### Run Step Delta + - `id: String` -- `RunStepDelta = untyped` + The unique ID of the local shell call. -### Run Step Delta Event + - `action: Action{ command, env, type, 3 more}` -- `class RunStepDeltaEvent` + Execute a shell command on the server. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `command: Array[String]` - - `id: String` + The command to run. - The identifier of the run step, which can be referenced in API endpoints. + - `env: Hash[Symbol, String]` - - `delta: untyped` + Environment variables to set for the command. - - `object: :"thread.run.step.delta"` + - `type: :exec` - The object type, which is always `thread.run.step.delta`. + The type of the local shell action. Always `exec`. - - `:"thread.run.step.delta"` + - `:exec` -### Run Step Delta Message Delta + - `timeout_ms: Integer` -- `class RunStepDeltaMessageDelta` + Optional timeout in milliseconds for the command. - Details of the message creation by the run step. + - `user: String` - - `type: :message_creation` + Optional user to run the command as. - Always `message_creation`. + - `working_directory: String` - - `:message_creation` + Optional working directory to run the command in. - - `message_creation: MessageCreation{ message_id}` + - `call_id: String` - - `message_id: String` + The unique ID of the local shell tool call generated by the model. - The ID of the message that was created by this run step. + - `status: :in_progress | :completed | :incomplete` -### Run Step Include + The status of the local shell call. -- `RunStepInclude = :"step_details.tool_calls[*].file_search.results[*].content"` + - `:in_progress` - - `:"step_details.tool_calls[*].file_search.results[*].content"` + - `:completed` -### Tool Call + - `:incomplete` -- `ToolCall = untyped` + - `type: :local_shell_call` -### Tool Call Delta + The type of the local shell call. Always `local_shell_call`. -- `ToolCallDelta = untyped` + - `:local_shell_call` -### Tool Call Delta Object + - `agent: Agent{ agent_name}` -- `class ToolCallDeltaObject` + The agent that produced this item. - Details of the tool call. + - `agent_name: String` - - `type: :tool_calls` + The canonical name of the agent that produced this item. - Always `tool_calls`. + - `class LocalShellCallOutput` - - `:tool_calls` + The output of a local shell tool call. - - `tool_calls: Array[untyped]` + - `id: String` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The unique ID of the local shell tool call generated by the model. -### Tool Calls Step Details + - `output: String` -- `class ToolCallsStepDetails` + A JSON string of the output of the local shell tool call. - Details of the tool call. + - `type: :local_shell_call_output` - - `tool_calls: Array[untyped]` + The type of the local shell tool call output. Always `local_shell_call_output`. - 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`. + - `:local_shell_call_output` - - `type: :tool_calls` + - `agent: Agent{ agent_name}` - Always `tool_calls`. + The agent that produced this item. - - `:tool_calls` + - `agent_name: String` -# Messages + The canonical name of the agent that produced this item. -## List messages + - `status: :in_progress | :completed | :incomplete` -`beta.threads.messages.list(thread_id, **kwargs) -> CursorPage` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. -**get** `/threads/{thread_id}/messages` + - `:in_progress` -List messages + - `:completed` -### Parameters + - `:incomplete` -- `thread_id: String` + - `class BetaResponseFunctionShellToolCall` -- `after: String` + A tool call that executes one or more shell commands in a managed environment. - 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. + - `id: String` -- `before: String` + The unique ID of the shell tool call. Populated when this item is returned via API. - 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. + - `action: Action{ commands, max_output_length, timeout_ms}` -- `limit: Integer` + The shell commands and limits that describe how to run the tool call. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `commands: Array[String]` -- `order: :asc | :desc` + - `max_output_length: Integer` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + Optional maximum number of characters to return from each command. - - `:asc` + - `timeout_ms: Integer` - - `:desc` + Optional timeout in milliseconds for the commands. -- `run_id: String` + - `call_id: String` - Filter messages by the run ID that generated them. + The unique ID of the shell tool call generated by the model. -### Returns + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` -- `class Message` + Represents the use of a local environment to perform shell actions. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaResponseLocalEnvironment` - - `id: String` + Represents the use of a local environment to perform shell actions. - The identifier, which can be referenced in API endpoints. + - `type: :local` - - `assistant_id: String` + The environment type. Always `local`. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `:local` - - `attachments: Array[Attachment{ file_id, tools}]` + - `class BetaResponseContainerReference` - A list of files attached to the message, and the tools they were added to. + Represents a container created with /v1/containers. - - `file_id: String` + - `container_id: String` - The ID of the file to attach to the message. + - `type: :container_reference` - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + The environment type. Always `container_reference`. - The tools to add this file to. + - `:container_reference` - - `class CodeInterpreterTool` + - `status: :in_progress | :completed | :incomplete` - - `type: :code_interpreter` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The type of tool being defined: `code_interpreter` + - `:in_progress` - - `:code_interpreter` + - `:completed` - - `class AssistantToolsFileSearchTypeOnly` + - `:incomplete` - - `type: :file_search` + - `type: :shell_call` - The type of tool being defined: `file_search` + The type of the item. Always `shell_call`. - - `:file_search` + - `:shell_call` - - `completed_at: Integer` + - `agent: Agent{ agent_name}` - The Unix timestamp (in seconds) for when the message was completed. + The agent that produced this item. - - `content: Array[untyped]` + - `agent_name: String` - The content of the message in array of text and/or images. + The canonical name of the agent that produced this item. - - `created_at: Integer` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The Unix timestamp (in seconds) for when the message was created. + The execution context that produced this tool call. - - `incomplete_at: Integer` + - `class Direct` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `type: :direct` - - `incomplete_details: IncompleteDetails{ reason}` + - `:direct` - On an incomplete message, details about why the message is incomplete. + - `class Program` - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + - `caller_id: String` - The reason the message is incomplete. + The call ID of the program item that produced this tool call. - - `:content_filter` + - `type: :program` - - `:max_tokens` + - `:program` - - `:run_cancelled` + - `created_by: String` - - `:run_expired` + The ID of the entity that created this tool call. - - `:run_failed` + - `class BetaResponseFunctionShellToolCallOutput` - - `metadata: Metadata` + The output of a shell tool call that was emitted. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `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 shell call output. Populated when this item is returned via API. - - `object: :"thread.message"` + - `call_id: String` - The object type, which is always `thread.message`. + The unique ID of the shell tool call generated by the model. - - `:"thread.message"` + - `max_output_length: Integer` - - `role: :user | :assistant` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The entity that produced the message. One of `user` or `assistant`. + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `:user` + An array of shell call output contents - - `:assistant` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `run_id: String` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The ID of the [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. + - `class Timeout` - - `status: :in_progress | :incomplete | :completed` + Indicates that the shell call exceeded its configured time limit. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `type: :timeout` - - `:in_progress` + The outcome type. Always `timeout`. - - `:incomplete` + - `:timeout` - - `:completed` + - `class Exit` - - `thread_id: String` + Indicates that the shell commands finished and returned an exit code. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `exit_code: Integer` -### Example + Exit code from the shell process. -```ruby -require "openai" + - `type: :exit` -openai = OpenAI::Client.new(api_key: "My API Key") + The outcome type. Always `exit`. -page = openai.beta.threads.messages.list("thread_id") + - `:exit` -puts(page) -``` + - `stderr: String` -#### Response + The standard error output that was captured. -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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" -} -``` + - `stdout: String` -## Create message + The standard output that was captured. -`beta.threads.messages.create(thread_id, **kwargs) -> Message` + - `created_by: String` -**post** `/threads/{thread_id}/messages` + The identifier of the actor that created the item. -Create message + - `status: :in_progress | :completed | :incomplete` -### Parameters + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. -- `thread_id: String` + - `:in_progress` -- `content: String | Array[MessageContentPartParam]` + - `:completed` - The text contents of the message. + - `:incomplete` - - `String = String` + - `type: :shell_call_output` - The text contents of the message. + The type of the shell call output. Always `shell_call_output`. - - `ArrayOfContentParts = Array[MessageContentPartParam]` + - `:shell_call_output` - 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: Agent{ agent_name}` - - `class ImageFileContentBlock` + The agent that produced this item. - References an image [File](https://platform.openai.com/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_: Direct{ type} | Program{ 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. - - `detail: :auto | :low | :high` + - `class 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`. + - `type: :direct` - - `:auto` + - `:direct` - - `:low` + - `class Program` - - `: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` - - `class ImageURLContentBlock` + - `created_by: String` - References an image URL in the content of a message. + The identifier of the actor that created the item. - - `image_url: ImageURL` + - `class BetaResponseApplyPatchToolCall` - - `url: String` + A tool call that applies file diffs by creating, deleting, or updating files. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `id: String` - - `detail: :auto | :low | :high` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `call_id: String` - - `:auto` + The unique ID of the apply patch tool call generated by the model. - - `:low` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `:high` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `type: :image_url` + - `class CreateFile` - The type of the content part. + Instruction describing how to create a file via the apply_patch tool. - - `:image_url` + - `diff: String` - - `class TextContentBlockParam` + Diff to apply. - The text content that is part of a message. + - `path: String` - - `text: String` + Path of the file to create. - Text content to be sent to the model + - `type: :create_file` - - `type: :text` + Create a new file with the provided diff. - Always `text`. + - `:create_file` - - `:text` + - `class DeleteFile` -- `role: :user | :assistant` + Instruction describing how to delete a file via the apply_patch tool. - The role of the entity that is creating the message. Allowed values include: + - `path: 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. + Path of the file to delete. - - `:user` + - `type: :delete_file` - - `:assistant` + Delete the specified file. -- `attachments: Array[Attachment{ file_id, tools}]` + - `:delete_file` - A list of files attached to the message, and the tools they should be added to. + - `class UpdateFile` - - `file_id: String` + Instruction describing how to update a file via the apply_patch tool. - The ID of the file to attach to the message. + - `diff: String` - - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` + Diff to apply. - The tools to add this file to. + - `path: String` - - `class CodeInterpreterTool` + Path of the file to update. - - `type: :code_interpreter` + - `type: :update_file` - The type of tool being defined: `code_interpreter` + Update an existing file with the provided diff. - - `:code_interpreter` + - `:update_file` - - `class FileSearch` + - `status: :in_progress | :completed` - - `type: :file_search` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The type of tool being defined: `file_search` + - `:in_progress` - - `:file_search` + - `:completed` -- `metadata: Metadata` + - `type: :apply_patch_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. + The type of the item. Always `apply_patch_call`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:apply_patch_call` -### Returns + - `agent: Agent{ agent_name}` -- `class Message` + The agent that produced this item. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent_name: String` - - `id: String` + The canonical name of the agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `assistant_id: String` + The execution context that produced this tool call. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `class Direct` - - `attachments: Array[Attachment{ file_id, tools}]` + - `type: :direct` - A list of files attached to the message, and the tools they were added to. + - `:direct` - - `file_id: String` + - `class Program` - The ID of the file to attach to the message. + - `caller_id: String` - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + The call ID of the program item that produced this tool call. - The tools to add this file to. + - `type: :program` - - `class CodeInterpreterTool` + - `:program` - - `type: :code_interpreter` + - `created_by: String` - The type of tool being defined: `code_interpreter` + The ID of the entity that created this tool call. - - `:code_interpreter` + - `class BetaResponseApplyPatchToolCallOutput` - - `class AssistantToolsFileSearchTypeOnly` + The output emitted by an apply patch tool call. - - `type: :file_search` + - `id: String` - The type of tool being defined: `file_search` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `:file_search` + - `call_id: String` - - `completed_at: Integer` + The unique ID of the apply patch tool call generated by the model. - The Unix timestamp (in seconds) for when the message was completed. + - `status: :completed | :failed` - - `content: Array[untyped]` + The status of the apply patch tool call output. One of `completed` or `failed`. - The content of the message in array of text and/or images. + - `:completed` - - `created_at: Integer` + - `:failed` - The Unix timestamp (in seconds) for when the message was created. + - `type: :apply_patch_call_output` - - `incomplete_at: Integer` + The type of the item. Always `apply_patch_call_output`. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `:apply_patch_call_output` - - `incomplete_details: IncompleteDetails{ reason}` + - `agent: Agent{ agent_name}` - On an incomplete message, details about why the message is incomplete. + The agent that produced this item. - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + - `agent_name: String` - The reason the message is incomplete. + The canonical name of the agent that produced this item. - - `:content_filter` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:max_tokens` + The execution context that produced this tool call. - - `:run_cancelled` + - `class Direct` - - `:run_expired` + - `type: :direct` - - `:run_failed` + - `:direct` - - `metadata: Metadata` + - `class Program` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `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.message"` + - `type: :program` - The object type, which is always `thread.message`. + - `:program` - - `:"thread.message"` + - `created_by: String` - - `role: :user | :assistant` + The ID of the entity that created this tool call output. - The entity that produced the message. One of `user` or `assistant`. + - `output: String` - - `:user` + Optional textual output returned by the apply patch tool. - - `:assistant` + - `class McpCall` - - `run_id: String` + An invocation of a tool on an MCP server. - 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. + - `id: String` - - `status: :in_progress | :incomplete | :completed` + The unique ID of the tool call. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `arguments: String` - - `:in_progress` + A JSON string of the arguments passed to the tool. - - `:incomplete` + - `name: String` - - `:completed` + The name of the tool that was run. - - `thread_id: String` + - `server_label: String` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The label of the MCP server running the tool. -### Example + - `type: :mcp_call` -```ruby -require "openai" + The type of the item. Always `mcp_call`. -openai = OpenAI::Client.new(api_key: "My API Key") + - `:mcp_call` -message = openai.beta.threads.messages.create("thread_id", content: "string", role: :user) + - `agent: Agent{ agent_name}` -puts(message) -``` + The agent that produced this item. -#### Response + - `agent_name: String` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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 canonical name of the agent that produced this item. -## Modify message + - `approval_request_id: String` -`beta.threads.messages.update(message_id, **kwargs) -> Message` + 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. -**post** `/threads/{thread_id}/messages/{message_id}` + - `error: String` -Modify message + The error from the tool call, if any. -### Parameters + - `output: String` -- `thread_id: String` + The output from the tool call. -- `message_id: String` + - `status: :in_progress | :completed | :incomplete | 2 more` -- `metadata: Metadata` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `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. + - `:in_progress` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:completed` -### Returns + - `:incomplete` -- `class Message` + - `:calling` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `:failed` - - `id: String` + - `class McpListTools` - The identifier, which can be referenced in API endpoints. + A list of tools available on an MCP server. - - `assistant_id: String` + - `id: String` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The unique ID of the list. - - `attachments: Array[Attachment{ file_id, tools}]` + - `server_label: String` - A list of files attached to the message, and the tools they were added to. + The label of the MCP server. - - `file_id: String` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - The ID of the file to attach to the message. + The tools available on the server. - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + - `input_schema: untyped` - The tools to add this file to. + The JSON schema describing the tool's input. - - `class CodeInterpreterTool` + - `name: String` - - `type: :code_interpreter` + The name of the tool. - The type of tool being defined: `code_interpreter` + - `annotations: untyped` - - `:code_interpreter` + Additional annotations about the tool. - - `class AssistantToolsFileSearchTypeOnly` + - `description: String` - - `type: :file_search` + The description of the tool. - The type of tool being defined: `file_search` + - `type: :mcp_list_tools` - - `:file_search` + The type of the item. Always `mcp_list_tools`. - - `completed_at: Integer` + - `:mcp_list_tools` - The Unix timestamp (in seconds) for when the message was completed. + - `agent: Agent{ agent_name}` - - `content: Array[untyped]` + The agent that produced this item. - The content of the message in array of text and/or images. + - `agent_name: String` - - `created_at: Integer` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the message was created. + - `error: String` - - `incomplete_at: Integer` + Error message if the server could not list tools. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `class McpApprovalRequest` - - `incomplete_details: IncompleteDetails{ reason}` + A request for human approval of a tool invocation. - On an incomplete message, details about why the message is incomplete. + - `id: String` - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + The unique ID of the approval request. - The reason the message is incomplete. + - `arguments: String` - - `:content_filter` + A JSON string of arguments for the tool. - - `:max_tokens` + - `name: String` - - `:run_cancelled` + The name of the tool to run. - - `:run_expired` + - `server_label: String` - - `:run_failed` + The label of the MCP server making the request. - - `metadata: Metadata` + - `type: :mcp_approval_request` - Set of 16 key-value pairs that can be attached to an object. 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 item. Always `mcp_approval_request`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:mcp_approval_request` - - `object: :"thread.message"` + - `agent: Agent{ agent_name}` - The object type, which is always `thread.message`. + The agent that produced this item. - - `:"thread.message"` + - `agent_name: String` - - `role: :user | :assistant` + The canonical name of the agent that produced this item. - The entity that produced the message. One of `user` or `assistant`. + - `class McpApprovalResponse` - - `:user` + A response to an MCP approval request. - - `:assistant` + - `id: String` - - `run_id: String` + The unique ID of the approval response - 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. + - `approval_request_id: String` - - `status: :in_progress | :incomplete | :completed` + The ID of the approval request being answered. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `approve: bool` - - `:in_progress` + Whether the request was approved. - - `:incomplete` + - `type: :mcp_approval_response` - - `:completed` + The type of the item. Always `mcp_approval_response`. - - `thread_id: String` + - `:mcp_approval_response` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `agent: Agent{ agent_name}` -### Example + The agent that produced this item. -```ruby -require "openai" + - `agent_name: String` -openai = OpenAI::Client.new(api_key: "My API Key") + The canonical name of the agent that produced this item. -message = openai.beta.threads.messages.update("message_id", thread_id: "thread_id") + - `reason: String` -puts(message) -``` + Optional reason for the decision. -#### Response + - `class BetaResponseCustomToolCall` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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" -} -``` + A call to a custom tool created by the model. -## Retrieve message + - `class BetaResponseCustomToolCallOutputItem` -`beta.threads.messages.retrieve(message_id, **kwargs) -> Message` + The output of a custom tool call from your code, being sent back to the model. -**get** `/threads/{thread_id}/messages/{message_id}` + - `id: String` -Retrieve message + The unique ID of the custom tool call output item. -### Parameters + - `status: :in_progress | :completed | :incomplete` -- `thread_id: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -- `message_id: String` + - `:in_progress` -### Returns + - `:completed` -- `class Message` + - `:incomplete` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `created_by: String` - - `id: String` + The identifier of the actor that created the item. - The identifier, which can be referenced in API endpoints. + - `parallel_tool_calls: bool` - - `assistant_id: String` + Whether to allow the model to run tool calls in parallel. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `temperature: Float` - - `attachments: Array[Attachment{ file_id, tools}]` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - A list of files attached to the message, and the tools they were added to. + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `file_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 file to attach to the message. + - `BetaToolChoiceOptions = :none | :auto | :required` - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + Controls which (if any) tool is called by the model. - The tools to add this file to. + `none` means the model will not call any tool and instead generates a message. - - `class CodeInterpreterTool` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `type: :code_interpreter` + `required` means the model must call one or more tools. - The type of tool being defined: `code_interpreter` + - `:none` - - `:code_interpreter` + - `:auto` - - `class AssistantToolsFileSearchTypeOnly` + - `:required` - - `type: :file_search` + - `class BetaToolChoiceAllowed` - The type of tool being defined: `file_search` + Constrains the tools available to the model to a pre-defined set. - - `:file_search` + - `mode: :auto | :required` - - `completed_at: Integer` + Constrains the tools available to the model to a pre-defined set. - The Unix timestamp (in seconds) for when the message was completed. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `content: Array[untyped]` + `required` requires the model to call one or more of the allowed tools. - The content of the message in array of text and/or images. + - `:auto` - - `created_at: Integer` + - `:required` - The Unix timestamp (in seconds) for when the message was created. + - `tools: Array[Hash[Symbol, untyped]]` - - `incomplete_at: Integer` + A list of tool definitions that the model should be allowed to call. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + For the Responses API, the list of tool definitions might look like: - - `incomplete_details: IncompleteDetails{ reason}` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - On an incomplete message, details about why the message is incomplete. + - `type: :allowed_tools` - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + Allowed tool configuration type. Always `allowed_tools`. - The reason the message is incomplete. + - `:allowed_tools` - - `:content_filter` + - `class BetaToolChoiceTypes` - - `:max_tokens` + 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). - - `:run_cancelled` + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `:run_expired` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `:run_failed` + Allowed values are: - - `metadata: Metadata` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `:file_search` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:web_search_preview` - - `object: :"thread.message"` + - `:computer` - The object type, which is always `thread.message`. + - `:computer_use_preview` - - `:"thread.message"` + - `:computer_use` - - `role: :user | :assistant` + - `:web_search_preview_2025_03_11` - The entity that produced the message. One of `user` or `assistant`. + - `:image_generation` - - `:user` + - `:code_interpreter` - - `:assistant` + - `class BetaToolChoiceFunction` - - `run_id: String` + Use this option to force the model to call a specific function. - 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. + - `name: String` - - `status: :in_progress | :incomplete | :completed` + The name of the function to call. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `type: :function` - - `:in_progress` + For function calling, the type is always `function`. - - `:incomplete` + - `:function` - - `:completed` + - `class BetaToolChoiceMcp` - - `thread_id: String` + Use this option to force the model to call a specific tool on a remote MCP server. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `server_label: String` -### Example + The label of the MCP server to use. -```ruby -require "openai" + - `type: :mcp` -openai = OpenAI::Client.new(api_key: "My API Key") + For MCP tools, the type is always `mcp`. -message = openai.beta.threads.messages.retrieve("message_id", thread_id: "thread_id") + - `:mcp` -puts(message) -``` + - `name: String` -#### Response + The name of the tool to call on the server. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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" -} -``` + - `class BetaToolChoiceCustom` -## Delete message + Use this option to force the model to call a specific custom tool. -`beta.threads.messages.delete(message_id, **kwargs) -> MessageDeleted` + - `name: String` -**delete** `/threads/{thread_id}/messages/{message_id}` + The name of the custom tool to call. -Delete message + - `type: :custom` -### Parameters + For custom tool calling, the type is always `custom`. -- `thread_id: String` + - `:custom` -- `message_id: String` + - `class BetaSpecificProgrammaticToolCallingParam` -### Returns + - `type: :programmatic_tool_calling` -- `class MessageDeleted` + The tool to call. Always `programmatic_tool_calling`. - - `id: String` + - `:programmatic_tool_calling` - - `deleted: bool` + - `class BetaToolChoiceApplyPatch` - - `object: :"thread.message.deleted"` + Forces the model to call the apply_patch tool when executing a tool call. - - `:"thread.message.deleted"` + - `type: :apply_patch` -### Example + The tool to call. Always `apply_patch`. -```ruby -require "openai" + - `:apply_patch` -openai = OpenAI::Client.new(api_key: "My API Key") + - `class BetaToolChoiceShell` -message_deleted = openai.beta.threads.messages.delete("message_id", thread_id: "thread_id") + Forces the model to call the shell tool when a tool call is required. -puts(message_deleted) -``` + - `type: :shell` -#### Response + The tool to call. Always `shell`. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + - `:shell` -## Domain Types + - `tools: Array[BetaTool]` -### Annotation + 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. -- `Annotation = untyped` + We support the following categories of tools: -### Annotation Delta + - **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. -- `AnnotationDelta = untyped` + - `class BetaFunctionTool` -### File Citation 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). -- `class FileCitationAnnotation` + - `class BetaFileSearchTool` - 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 that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `end_index: Integer` + - `class BetaComputerTool` - - `file_citation: FileCitation{ file_id}` + 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` + - `class BetaComputerUsePreviewTool` - The ID of the specific File the citation is from. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `start_index: Integer` + - `class BetaWebSearchTool` - - `text: 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 in the message content that needs to be replaced. + - `class Mcp` - - `type: :file_citation` + 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). - Always `file_citation`. + - `class CodeInterpreter` - - `:file_citation` + A tool that runs Python code to help generate a response to a prompt. -### File Citation Delta Annotation + - `class ProgrammaticToolCalling` -- `class FileCitationDeltaAnnotation` + - `class ImageGeneration` - 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 that generates images using the GPT image models. - - `index: Integer` + - `class LocalShell` - The index of the annotation in the text content part. + A tool that allows the model to execute shell commands in a local environment. - - `type: :file_citation` + - `class BetaFunctionShellTool` - Always `file_citation`. + A tool that allows the model to execute shell commands. - - `:file_citation` + - `class BetaCustomTool` - - `end_index: Integer` + 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_citation: FileCitation{ file_id, quote}` + - `class BetaNamespaceTool` - - `file_id: String` + Groups function/custom tools under a shared namespace. - The ID of the specific File the citation is from. + - `class BetaToolSearchTool` - - `quote: String` + Hosted or BYOT tool search configuration for deferred tools. - The specific quote in the file. + - `class BetaWebSearchPreviewTool` - - `start_index: Integer` + 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` + - `class BetaApplyPatchTool` - The text in the message content that needs to be replaced. + Allows the assistant to create, delete, or update files using unified diffs. -### File Path Annotation + - `top_p: Float` -- `class FilePathAnnotation` + 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 URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + We generally recommend altering this or `temperature` but not both. - - `end_index: Integer` + - `background: bool` - - `file_path: FilePath{ file_id}` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `file_id: String` + - `completed_at: Float` - The ID of the file that was generated. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `start_index: Integer` + - `conversation: Conversation{ id}` - - `text: String` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The text in the message content that needs to be replaced. + - `id: String` - - `type: :file_path` + The unique ID of the conversation that this response was associated with. - Always `file_path`. + - `max_output_tokens: Integer` - - `:file_path` + 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). -### File Path Delta Annotation + - `max_tool_calls: Integer` -- `class FilePathDeltaAnnotation` + 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 URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `moderation: Moderation{ input, output}` - - `index: Integer` + Moderation results for the response input and output, if moderated completions were requested. - The index of the annotation in the text content part. + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `type: :file_path` + Moderation for the response input. - Always `file_path`. + - `class ModerationResult` - - `:file_path` + A moderation result produced for the response input or output. - - `end_index: Integer` + - `categories: Hash[Symbol, bool]` - - `file_path: FilePath{ file_id}` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `file_id: String` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - The ID of the file that was generated. + Which modalities of input are reflected by the score for each category. - - `start_index: Integer` + - `:text` - - `text: String` + - `:image` - The text in the message content that needs to be replaced. + - `category_scores: Hash[Symbol, Float]` -### Image File + A dictionary of moderation categories to scores. -- `class ImageFile` + - `flagged: bool` - - `file_id: String` + A boolean indicating whether the content was flagged by any category. - 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. + - `model: String` - - `detail: :auto | :low | :high` + The moderation model that produced this result. - 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: :moderation_result` - - `:auto` + The object type, which was always `moderation_result` for successful moderation results. - - `:low` + - `:moderation_result` - - `:high` + - `class Error` -### Image File Content Block + An error produced while attempting moderation for the response input or output. -- `class ImageFileContentBlock` + - `code: String` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The error code. - - `image_file: ImageFile` + - `message: String` - - `file_id: String` + The error message. - 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: :error` - - `detail: :auto | :low | :high` + The object type, which was always `error` for moderation failures. - 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`. + - `:error` - - `:auto` + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `:low` + Moderation for the response output. - - `:high` + - `class ModerationResult` - - `type: :image_file` + A moderation result produced for the response input or output. - Always `image_file`. + - `categories: Hash[Symbol, bool]` - - `:image_file` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. -### Image File Delta + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` -- `class ImageFileDelta` + Which modalities of input are reflected by the score for each category. - - `detail: :auto | :low | :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`. + - `:image` - - `:auto` + - `category_scores: Hash[Symbol, Float]` - - `:low` + A dictionary of moderation categories to scores. - - `:high` + - `flagged: bool` - - `file_id: String` + A boolean indicating whether the content was flagged by any category. - 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. + - `model: String` -### Image File Delta Block + The moderation model that produced this result. -- `class ImageFileDeltaBlock` + - `type: :moderation_result` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The object type, which was always `moderation_result` for successful moderation results. - - `index: Integer` + - `:moderation_result` - The index of the content part in the message. + - `class Error` - - `type: :image_file` + An error produced while attempting moderation for the response input or output. - Always `image_file`. + - `code: String` - - `:image_file` + The error code. - - `image_file: ImageFileDelta` + - `message: String` - - `detail: :auto | :low | :high` + The error message. - 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: :error` - - `:auto` + The object type, which was always `error` for moderation failures. - - `:low` + - `:error` - - `:high` + - `previous_response_id: String` - - `file_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 [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. + - `prompt: BetaResponsePrompt` -### Image URL + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). -- `class ImageURL` + - `id: String` - - `url: String` + The unique identifier of the prompt template to use. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `detail: :auto | :low | :high` + 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. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `String = String` - - `:auto` + - `class BetaResponseInputText` - - `:low` + A text input to the model. - - `:high` + - `class BetaResponseInputImage` -### Image URL Content Block + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -- `class ImageURLContentBlock` + - `class BetaResponseInputFile` - References an image URL in the content of a message. + A file input to the model. - - `image_url: ImageURL` + - `version: String` - - `url: String` + Optional version of the prompt template. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `prompt_cache_key: String` - - `detail: :auto | :low | :high` + 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). - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `:auto` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `:low` + - `mode: :implicit | :explicit` - - `:high` + Whether implicit prompt-cache breakpoints were enabled. - - `type: :image_url` + - `:implicit` - The type of the content part. + - `:explicit` - - `:image_url` + - `ttl: :"30m"` -### Image URL Delta + The minimum lifetime applied to each cache breakpoint. -- `class ImageURLDelta` + - `:"30m"` - - `detail: :auto | :low | :high` + - `prompt_cache_retention: :in_memory | :"24h"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `:auto` + 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. - - `:low` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `:high` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `url: String` + - `:in_memory` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `:"24h"` -### Image URL Delta Block + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` -- `class ImageURLDeltaBlock` + **gpt-5 and o-series models only** - References an image URL in the content of a message. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `index: Integer` + - `context: :auto | :current_turn | :all_turns` - The index of the content part in the message. + 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: :image_url` + - `:auto` - Always `image_url`. + - `:current_turn` - - `:image_url` + - `:all_turns` - - `image_url: ImageURLDelta` + - `effort: :none | :minimal | :low | 4 more` - - `detail: :auto | :low | :high` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `:none` - - `:auto` + - `:minimal` - `:low` - - `:high` - - - `url: String` + - `:medium` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `:high` -### Message + - `:xhigh` -- `class Message` + - `:max` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `generate_summary: :auto | :concise | :detailed` - - `id: String` + **Deprecated:** use `summary` instead. - The identifier, which can be referenced in API endpoints. + 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`. - - `assistant_id: String` + - `:auto` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `:concise` - - `attachments: Array[Attachment{ file_id, tools}]` + - `:detailed` - A list of files attached to the message, and the tools they were added to. + - `mode: String | :standard | :pro` - - `file_id: String` + Controls the reasoning execution mode for the request. - The ID of the file to attach to the message. + When returned on a response, this is the effective execution mode. - - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` + - `String = String` - The tools to add this file to. + - `Mode = :standard | :pro` - - `class CodeInterpreterTool` + Controls the reasoning execution mode for the request. - - `type: :code_interpreter` + When returned on a response, this is the effective execution mode. - The type of tool being defined: `code_interpreter` + - `:standard` - - `:code_interpreter` + - `:pro` - - `class AssistantToolsFileSearchTypeOnly` + - `summary: :auto | :concise | :detailed` - - `type: :file_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`. - The type of tool being defined: `file_search` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `:file_search` + - `:auto` - - `completed_at: Integer` + - `:concise` - The Unix timestamp (in seconds) for when the message was completed. + - `:detailed` - - `content: Array[untyped]` + - `safety_identifier: String` - The content of the message in array of text and/or images. + 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). - - `created_at: Integer` + - `service_tier: :auto | :default | :flex | 2 more` - The Unix timestamp (in seconds) for when the message was created. + Specifies the processing type used for serving the request. - - `incomplete_at: Integer` + - 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 Unix timestamp (in seconds) for when the message was marked as incomplete. + 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. - - `incomplete_details: IncompleteDetails{ reason}` + - `:auto` - On an incomplete message, details about why the message is incomplete. + - `:default` - - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` + - `:flex` - The reason the message is incomplete. + - `:scale` - - `:content_filter` + - `:priority` - - `:max_tokens` + - `status: BetaResponseStatus` - - `:run_cancelled` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `:run_expired` + - `:completed` - - `:run_failed` + - `:failed` - - `metadata: 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. + - `:cancelled` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:queued` - - `object: :"thread.message"` + - `:incomplete` - The object type, which is always `thread.message`. + - `text: BetaResponseTextConfig` - - `:"thread.message"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `role: :user | :assistant` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The entity that produced the message. One of `user` or `assistant`. + - `format_: BetaResponseFormatTextConfig` - - `:user` + An object specifying the format that the model must output. - - `:assistant` + 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). - - `run_id: String` + The default format is `{ "type": "text" }` with no additional options. - 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. + **Not recommended for gpt-4o and newer models:** - - `status: :in_progress | :incomplete | :completed` + 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 message, which can be either `in_progress`, `incomplete`, or `completed`. + - `class Text` - - `:in_progress` + Default response format. Used to generate text responses. - - `:incomplete` + - `type: :text` - - `:completed` + The type of response format being defined. Always `text`. - - `thread_id: String` + - `:text` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `class BetaResponseFormatTextJSONSchemaConfig` -### Message Content + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). -- `MessageContent = untyped` + - `name: String` -### Message Content Delta + 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. -- `MessageContentDelta = untyped` + - `schema: Hash[Symbol, untyped]` -### Message Content Part Param + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). -- `MessageContentPartParam = ImageFileContentBlock | ImageURLContentBlock | TextContentBlockParam` + - `type: :json_schema` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The type of response format being defined. Always `json_schema`. - - `class ImageFileContentBlock` + - `:json_schema` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `description: String` - - `image_file: ImageFile` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `file_id: String` + - `strict: bool` - 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 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). - - `detail: :auto | :low | :high` + - `class JSONObject` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `:auto` + - `type: :json_object` - - `:low` + The type of response format being defined. Always `json_object`. - - `:high` + - `:json_object` - - `type: :image_file` + - `verbosity: :low | :medium | :high` - Always `image_file`. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `:image_file` + - `:low` - - `class ImageURLContentBlock` + - `:medium` - References an image URL in the content of a message. + - `:high` - - `image_url: ImageURL` + - `top_logprobs: Integer` - - `url: 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 external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `truncation: :auto | :disabled` - - `detail: :auto | :low | :high` + The truncation strategy to use for the model response. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `auto`: 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` - - `:low` + - `:disabled` - - `:high` + - `usage: BetaResponseUsage` - - `type: :image_url` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The type of the content part. + - `input_tokens: Integer` - - `:image_url` + The number of input tokens. - - `class TextContentBlockParam` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - The text content that is part of a message. + A detailed breakdown of the input tokens. - - `text: String` + - `cache_write_tokens: Integer` - Text content to be sent to the model + The number of input tokens that were written to the cache. - - `type: :text` + - `cached_tokens: Integer` - Always `text`. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `:text` + - `output_tokens: Integer` -### Message Deleted + The number of output tokens. -- `class MessageDeleted` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - - `id: String` + A detailed breakdown of the output tokens. - - `deleted: bool` + - `reasoning_tokens: Integer` - - `object: :"thread.message.deleted"` + The number of reasoning tokens. - - `:"thread.message.deleted"` + - `total_tokens: Integer` -### Message Delta + The total number of tokens used. -- `class MessageDelta` + - `user: String` - The delta containing the fields that have changed on the Message. + 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). - - `content: Array[untyped]` +### Example - The content of the message in array of text and/or images. +```ruby +require "openai" - - `role: :user | :assistant` +openai = OpenAI::Client.new(api_key: "My API Key") - The entity that produced the message. One of `user` or `assistant`. +beta_response = openai.beta.responses.cancel("resp_677efb5139a88190b512bc3fef8e535d") - - `:user` +puts(beta_response) +``` - - `:assistant` +#### Response -### Message Delta Event +```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" +} +``` -- `class MessageDeltaEvent` +## Compact a response - Represents a message delta i.e. any changed fields on a message during streaming. +`beta.responses.compact(**kwargs) -> BetaCompactedResponse` - - `id: String` +**post** `/responses/compact?beta=true` - The identifier of the message, which can be referenced in API endpoints. +Compact a conversation. Returns a compacted response object. - - `delta: MessageDelta` +Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced). - The delta containing the fields that have changed on the Message. +### Parameters - - `content: Array[untyped]` +- `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - The content of the message in array of text and/or images. + 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. - - `role: :user | :assistant` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - The entity that produced the message. One of `user` or `assistant`. + 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. - - `:user` + - `:"gpt-5.6-sol"` - - `:assistant` + - `:"gpt-5.6-terra"` - - `object: :"thread.message.delta"` + - `:"gpt-5.6-luna"` - The object type, which is always `thread.message.delta`. + - `:"gpt-5.4"` - - `:"thread.message.delta"` + - `:"gpt-5.4-mini"` -### Refusal Content Block + - `:"gpt-5.4-nano"` -- `class RefusalContentBlock` + - `:"gpt-5.4-mini-2026-03-17"` - The refusal content generated by the assistant. + - `:"gpt-5.4-nano-2026-03-17"` - - `refusal: String` + - `:"gpt-5.3-chat-latest"` - - `type: :refusal` + - `:"gpt-5.2"` - Always `refusal`. + - `:"gpt-5.2-2025-12-11"` - - `:refusal` + - `:"gpt-5.2-chat-latest"` -### Refusal Delta Block + - `:"gpt-5.2-pro"` -- `class RefusalDeltaBlock` + - `:"gpt-5.2-pro-2025-12-11"` - The refusal content that is part of a message. + - `:"gpt-5.1"` - - `index: Integer` + - `:"gpt-5.1-2025-11-13"` - The index of the refusal part in the message. + - `:"gpt-5.1-codex"` - - `type: :refusal` + - `:"gpt-5.1-mini"` - Always `refusal`. + - `:"gpt-5.1-chat-latest"` - - `:refusal` + - `:"gpt-5"` - - `refusal: String` + - `:"gpt-5-mini"` -### Text + - `:"gpt-5-nano"` -- `class Text` + - `:"gpt-5-2025-08-07"` - - `annotations: Array[untyped]` + - `:"gpt-5-mini-2025-08-07"` - - `value: String` + - `:"gpt-5-nano-2025-08-07"` - The data that makes up the text. + - `:"gpt-5-chat-latest"` -### Text Content Block + - `:"gpt-4.1"` -- `class TextContentBlock` + - `:"gpt-4.1-mini"` - The text content that is part of a message. + - `:"gpt-4.1-nano"` - - `text: Text` + - `:"gpt-4.1-2025-04-14"` - - `annotations: Array[untyped]` + - `:"gpt-4.1-mini-2025-04-14"` - - `value: String` + - `:"gpt-4.1-nano-2025-04-14"` - The data that makes up the text. + - `:"o4-mini"` - - `type: :text` + - `:"o4-mini-2025-04-16"` - Always `text`. + - `:o3` - - `:text` + - `:"o3-2025-04-16"` -### Text Content Block Param + - `:"o3-mini"` -- `class TextContentBlockParam` + - `:"o3-mini-2025-01-31"` - The text content that is part of a message. + - `:o1` - - `text: String` + - `:"o1-2024-12-17"` - Text content to be sent to the model + - `:"o1-preview"` - - `type: :text` + - `:"o1-preview-2024-09-12"` - Always `text`. + - `:"o1-mini"` - - `:text` + - `:"o1-mini-2024-09-12"` -### Text Delta + - `:"gpt-4o"` -- `class TextDelta` + - `:"gpt-4o-2024-11-20"` - - `annotations: Array[untyped]` + - `:"gpt-4o-2024-08-06"` - - `value: String` + - `:"gpt-4o-2024-05-13"` - The data that makes up the text. + - `:"gpt-4o-audio-preview"` -### Text Delta Block + - `:"gpt-4o-audio-preview-2024-10-01"` -- `class TextDeltaBlock` + - `:"gpt-4o-audio-preview-2024-12-17"` - The text content that is part of a message. + - `:"gpt-4o-audio-preview-2025-06-03"` - - `index: Integer` + - `:"gpt-4o-mini-audio-preview"` - The index of the content part in the message. + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - - `type: :text` + - `:"gpt-4o-search-preview"` - Always `text`. + - `:"gpt-4o-mini-search-preview"` - - `:text` + - `:"gpt-4o-search-preview-2025-03-11"` - - `text: TextDelta` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - - `annotations: Array[untyped]` + - `:"chatgpt-4o-latest"` - - `value: String` + - `:"codex-mini-latest"` - The data that makes up the text. + - `:"gpt-4o-mini"` -# Responses + - `:"gpt-4o-mini-2024-07-18"` -## Create a model response + - `:"gpt-4-turbo"` -`beta.responses.create(**kwargs) -> BetaResponse` + - `:"gpt-4-turbo-2024-04-09"` -**post** `/responses?beta=true` + - `:"gpt-4-0125-preview"` -Create a model response + - `:"gpt-4-turbo-preview"` -### Parameters + - `:"gpt-4-1106-preview"` -- `background: bool` + - `:"gpt-4-vision-preview"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `:"gpt-4"` -- `context_management: Array[ContextManagement{ type, compact_threshold}]` + - `:"gpt-4-0314"` - Context management configuration for this request. + - `:"gpt-4-0613"` - - `type: String` + - `:"gpt-4-32k"` - The context management entry type. Currently only 'compaction' is supported. + - `:"gpt-4-32k-0314"` - - `compact_threshold: Integer` + - `:"gpt-4-32k-0613"` - Token threshold at which compaction should be triggered for this entry. + - `:"gpt-3.5-turbo"` -- `conversation: String | BetaResponseConversationParam` + - `:"gpt-3.5-turbo-16k"` - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `:"gpt-3.5-turbo-0301"` - - `String = String` + - `:"gpt-3.5-turbo-0613"` - The unique ID of the conversation. + - `:"gpt-3.5-turbo-1106"` - - `class BetaResponseConversationParam` + - `:"gpt-3.5-turbo-0125"` - The conversation that this response belongs to. + - `:"gpt-3.5-turbo-16k-0613"` - - `id: String` + - `:"o1-pro"` - The unique ID of the conversation. + - `:"o1-pro-2025-03-19"` -- `include: Array[BetaResponseIncludable]` + - `:"o3-pro"` - Specify additional output data to include in the model response. Currently supported values are: + - `:"o3-pro-2025-06-10"` - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `:"o3-deep-research"` - - `:"file_search_call.results"` + - `:"o3-deep-research-2025-06-26"` - - `:"web_search_call.results"` + - `:"o4-mini-deep-research"` - - `:"web_search_call.action.sources"` + - `:"o4-mini-deep-research-2025-06-26"` - - `:"message.input_image.image_url"` + - `:"computer-use-preview"` - - `:"computer_call_output.output.image_url"` + - `:"computer-use-preview-2025-03-11"` - - `:"code_interpreter_call.outputs"` + - `:"gpt-5-codex"` - - `:"reasoning.encrypted_content"` + - `:"gpt-5-pro"` - - `:"message.output_text.logprobs"` + - `:"gpt-5-pro-2025-10-06"` -- `input: String | BetaResponseInput` + - `:"gpt-5.1-codex-max"` - Text, image, or file inputs to the model, used to generate a response. + - `String = String` - Learn more: +- `input: String | Array[BetaResponseInputItem]` - - [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) + Text, image, or file inputs to the model, used to generate a response - `String = String` - A text input to the model, equivalent to a text input with the - `user` role. + A text input to the model, equivalent to a text input with the `user` role. - - `BetaResponseInput = Array[BetaResponseInputItem]` + - `UnionMember1 = Array[BetaResponseInputItem]` - A list of one or many input items to the model, containing - different content types. + A list of one or many input items to the model, containing different content types. - `class BetaEasyInputMessage` @@ -14202,7 +25144,7 @@ Create a model response - `:developer` - - `phase: :commentary` + - `phase: :commentary | :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 @@ -14210,6 +25152,8 @@ Create a model response - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -14449,7 +25393,7 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -14457,6 +25401,8 @@ Create a model response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -15629,7 +26575,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -15639,7 +26585,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -15686,7 +26636,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -15696,7 +26646,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -17849,325 +28803,15 @@ Create a model response - `instructions: String` A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - -- `max_output_tokens: Integer` - - 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: Integer` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - -- `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. - - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 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"` - - - `:"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 = String` - -- `moderation: Moderation{ model, policy}` - - Configuration for running moderation on the input and output of this response. - - - `model: String` - - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - - `policy: Policy{ input, output}` - - The policy to apply to moderated response input and output. - - - `input: Input{ mode}` - - The moderation policy for the response input. - - - `mode: :score | :block` - - - `:score` - - - `:block` - - - `output: Output{ mode}` - - The moderation policy for the response output. - - - `mode: :score | :block` - - - `:score` - - - `:block` - -- `multi_agent: MultiAgent{ enabled, max_concurrent_subagents}` - - Configuration for server-hosted multi-agent execution. - - - `enabled: bool` - - Whether to enable server-hosted multi-agent execution for this response. - - - `max_concurrent_subagents: Integer` - - `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. - -- `parallel_tool_calls: bool` - - Whether to allow the model to run tool calls in parallel. + 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. - `previous_response_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`. - -- `prompt: 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: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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 = String` - - - `class BetaResponseInputText` - - A text input to the model. - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile` - - A file input to the model. - - - `version: String` - - Optional version of the prompt template. + 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_cache_key: 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). + A key to use when reading from or writing to the prompt cache. - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` @@ -18189,127 +28833,15 @@ Create a model response - `prompt_cache_retention: :in_memory | :"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. + How long to retain a prompt cache entry created by this request. - `:in_memory` - `:"24h"` -- `reasoning: Reasoning{ 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: :auto | :current_turn | :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: :none | :minimal | :low | 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: :auto | :concise | :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: String | :standard | :pro` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `String = String` - - - `Mode = :standard | :pro` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `:standard` - - - `:pro` - - - `summary: :auto | :concise | :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: 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). - -- `service_tier: :auto | :default | :flex | 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](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'. +- `service_tier: :auto | :default | :flex | :priority` - 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 service tier to use for this request. - `:auto` @@ -18317,541 +28849,399 @@ Create a model response - `:flex` - - `:scale` - - `:priority` -- `store: bool` - - Whether to store the generated model response for later retrieval via - API. - -- `stream: bool` - - 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. - -- `stream_options: StreamOptions{ include_obfuscation}` - - Options for streaming responses. Only set this when you set `stream: true`. - - - `include_obfuscation: bool` - - 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. - -- `temperature: Float` - - 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. - -- `text: 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_: 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. +- `betas: Array[:"responses_multi_agent=v1"]` - - `class Text` + - `:"responses_multi_agent=v1"` - Default response format. Used to generate text responses. +### Returns - - `type: :text` +- `class BetaCompactedResponse` - The type of response format being defined. Always `text`. + - `id: String` - - `:text` + The unique identifier for the compacted response. - - `class BetaResponseFormatTextJSONSchemaConfig` + - `created_at: Integer` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Unix timestamp (in seconds) when the compacted conversation was created. - - `name: String` + - `object: :"response.compaction"` - 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 object type. Always `response.compaction`. - - `schema: Hash[Symbol, untyped]` + - `:"response.compaction"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `output: Array[BetaResponseOutputItem]` - - `type: :json_schema` + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - The type of response format being defined. Always `json_schema`. + - `class BetaResponseOutputMessage` - - `:json_schema` + An output message from the model. - - `description: String` + - `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 output message. - - `strict: bool` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - 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 content of the output message. - - `class JSONObject` + - `class BetaResponseOutputText` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + A text output from the model. - - `type: :json_object` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - The type of response format being defined. Always `json_object`. + The annotations of the text output. - - `:json_object` + - `class FileCitation` - - `verbosity: :low | :medium | :high` + A citation to a file. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `file_id: String` - - `:low` + The ID of the file. - - `:medium` + - `filename: String` - - `:high` + The filename of the file cited. -- `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `index: Integer` - 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 index of the file in the list of files. - - `BetaToolChoiceOptions = :none | :auto | :required` + - `type: :file_citation` - Controls which (if any) tool is called by the model. + The type of the file citation. Always `file_citation`. - `none` means the model will not call any tool and instead generates a message. + - `:file_citation` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `class URLCitation` - `required` means the model must call one or more tools. + A citation for a web resource used to generate a model response. - - `:none` + - `end_index: Integer` - - `:auto` + The index of the last character of the URL citation in the message. - - `:required` + - `start_index: Integer` - - `class BetaToolChoiceAllowed` + The index of the first character of the URL citation in the message. - Constrains the tools available to the model to a pre-defined set. + - `title: String` - - `mode: :auto | :required` + The title of the web resource. - Constrains the tools available to the model to a pre-defined set. + - `type: :url_citation` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The type of the URL citation. Always `url_citation`. - `required` requires the model to call one or more of the allowed tools. + - `:url_citation` - - `:auto` + - `url: String` - - `:required` + The URL of the web resource. - - `tools: Array[Hash[Symbol, untyped]]` + - `class ContainerFileCitation` - A list of tool definitions that the model should be allowed to call. + A citation for a container file used to generate a model response. - For the Responses API, the list of tool definitions might look like: + - `container_id: String` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The ID of the container file. - - `type: :allowed_tools` + - `end_index: Integer` - Allowed tool configuration type. Always `allowed_tools`. + The index of the last character of the container file citation in the message. - - `:allowed_tools` + - `file_id: String` - - `class BetaToolChoiceTypes` + The ID of the file. - 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). + - `filename: String` - - `type: :file_search | :web_search_preview | :computer | 5 more` + The filename of the container file cited. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `start_index: Integer` - Allowed values are: + The index of the first character of the container file citation in the message. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `type: :container_file_citation` - - `:file_search` + The type of the container file citation. Always `container_file_citation`. - - `:web_search_preview` + - `:container_file_citation` - - `:computer` + - `class FilePath` - - `:computer_use_preview` + A path to a file. - - `:computer_use` + - `file_id: String` - - `:web_search_preview_2025_03_11` + The ID of the file. - - `:image_generation` + - `index: Integer` - - `:code_interpreter` + The index of the file in the list of files. - - `class BetaToolChoiceFunction` + - `type: :file_path` - Use this option to force the model to call a specific function. + The type of the file path. Always `file_path`. - - `name: String` + - `:file_path` - The name of the function to call. + - `text: String` - - `type: :function` + The text output from the model. - For function calling, the type is always `function`. + - `type: :output_text` - - `:function` + The type of the output text. Always `output_text`. - - `class BetaToolChoiceMcp` + - `:output_text` - Use this option to force the model to call a specific tool on a remote MCP server. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `server_label: String` + - `token: String` - The label of the MCP server to use. + - `bytes: Array[Integer]` - - `type: :mcp` + - `logprob: Float` - For MCP tools, the type is always `mcp`. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `:mcp` + - `token: String` - - `name: String` + - `bytes: Array[Integer]` - The name of the tool to call on the server. + - `logprob: Float` - - `class BetaToolChoiceCustom` + - `class BetaResponseOutputRefusal` - Use this option to force the model to call a specific custom tool. + A refusal from the model. - - `name: String` + - `refusal: String` - The name of the custom tool to call. + The refusal explanation from the model. - - `type: :custom` + - `type: :refusal` - For custom tool calling, the type is always `custom`. + The type of the refusal. Always `refusal`. - - `:custom` + - `:refusal` - - `class BetaSpecificProgrammaticToolCallingParam` + - `role: :assistant` - - `type: :programmatic_tool_calling` + The role of the output message. Always `assistant`. - The tool to call. Always `programmatic_tool_calling`. + - `:assistant` - - `:programmatic_tool_calling` + - `status: :in_progress | :completed | :incomplete` - - `class BetaToolChoiceApplyPatch` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Forces the model to call the apply_patch tool when executing a tool call. + - `:in_progress` - - `type: :apply_patch` + - `:completed` - The tool to call. Always `apply_patch`. + - `:incomplete` - - `:apply_patch` + - `type: :message` - - `class BetaToolChoiceShell` + The type of the output message. Always `message`. - Forces the model to call the shell tool when a tool call is required. + - `:message` - - `type: :shell` + - `agent: Agent{ agent_name}` - The tool to call. Always `shell`. + The agent that produced this item. - - `:shell` + - `agent_name: String` -- `tools: Array[BetaTool]` + 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. + - `phase: :commentary | :final_answer` - We support the following categories of tools: + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - **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. + - `:commentary` - - `class BetaFunctionTool` + - `:final_answer` - 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). + - `class BetaResponseFileSearchToolCall` - - `class BetaFileSearchTool` + 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 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` - - `class BetaComputerTool` + The unique ID of the file search tool call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `queries: Array[String]` - - `class BetaComputerUsePreviewTool` + The queries used to search for files. - 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 | :searching | :completed | 2 more` - - `class BetaWebSearchTool` + 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](https://platform.openai.com/docs/guides/tools-web-search). + - `:in_progress` - - `class Mcp` + - `: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` - - `class CodeInterpreter` + - `:incomplete` - A tool that runs Python code to help generate a response to a prompt. + - `:failed` - - `class ProgrammaticToolCalling` + - `type: :file_search_call` - - `class ImageGeneration` + The type of the file search tool call. Always `file_search_call`. - A tool that generates images using the GPT image models. + - `:file_search_call` - - `class LocalShell` + - `agent: Agent{ agent_name}` - A tool that allows the model to execute shell commands in a local environment. + The agent that produced this item. - - `class BetaFunctionShellTool` + - `agent_name: String` - A tool that allows the model to execute shell commands. + The canonical name of the agent that produced this item. - - `class BetaCustomTool` + - `results: Array[Result{ attributes, file_id, filename, 2 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 results of the file search tool call. - - `class BetaNamespaceTool` + - `attributes: Hash[Symbol, String | Float | bool]` - Groups function/custom tools under a shared 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. - - `class BetaToolSearchTool` + - `String = String` - Hosted or BYOT tool search configuration for deferred tools. + - `Float = Float` - - `class BetaWebSearchPreviewTool` + - `UnionMember2 = bool` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_id: String` - - `class BetaApplyPatchTool` + The unique ID of the file. - Allows the assistant to create, delete, or update files using unified diffs. + - `filename: String` -- `top_logprobs: Integer` + The name of the 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. + - `score: Float` -- `top_p: Float` + The relevance score of the file - a value between 0 and 1. - 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. + - `text: String` - We generally recommend altering this or `temperature` but not both. + The text that was retrieved from the file. -- `truncation: :auto | :disabled` + - `class BetaResponseFunctionToolCall` - The truncation strategy to use for the model response. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) 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. + - `arguments: String` - - `:auto` + A JSON string of the arguments to pass to the function. - - `:disabled` + - `call_id: String` -- `user: String` + The unique ID of the function tool call generated by the model. - 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). + - `name: String` -- `betas: Array[:"responses_multi_agent=v1"]` + The name of the function to run. - - `:"responses_multi_agent=v1"` + - `type: :function_call` -### Returns + The type of the function tool call. Always `function_call`. -- `class BetaResponse` + - `:function_call` - `id: String` - Unique identifier for this Response. - - - `created_at: Float` - - 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 | :rate_limit_exceeded | :invalid_prompt | 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` + The unique ID of the function tool call. - - `:image_parse_error` + - `agent: Agent{ agent_name}` - - `:image_content_policy_violation` + The agent that produced this item. - - `:invalid_image_mode` + - `agent_name: String` - - `:image_file_too_large` + The canonical name of the agent that produced this item. - - `:unsupported_image_media_type` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:empty_image_file` + The execution context that produced this tool call. - - `:failed_to_download_image` + - `class Direct` - - `:image_file_not_found` + - `type: :direct` - - `message: String` + - `:direct` - A human-readable description of the error. + - `class Program` - - `incomplete_details: IncompleteDetails{ reason}` + - `caller_id: String` - Details about why the response is incomplete. + The call ID of the program item that produced this tool call. - - `reason: :max_output_tokens | :content_filter` + - `type: :program` - The reason why the response is incomplete. + - `:program` - - `:max_output_tokens` + - `namespace: String` - - `:content_filter` + The namespace of the function to run. - - `instructions: String | Array[BetaResponseInputItem]` + - `status: :in_progress | :completed | :incomplete` - A system (or developer) message inserted into the model's context. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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. + - `:in_progress` - - `String = String` + - `:completed` - A text input to the model, equivalent to a text input with the - `developer` role. + - `:incomplete` - - `InputItemList = Array[BetaResponseInputItem]` + - `class BetaResponseFunctionToolCallOutputItem` - A list of one or many input items to the model, containing - different content types. + - `id: String` - - `class BetaEasyInputMessage` + The unique ID of the function call tool output. - 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. + - `call_id: String` - - `content: String | BetaResponseInputMessageContentList` + The unique ID of the function tool call generated by the model. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the function call generated by your code. + Can be a string or an list of output content. - `String = String` - A text input to the model. + A string of the output of the function call. - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - A list of one or many input items to the model, containing different content - types. + Text, image, or file output of the function call. - `class BetaResponseInputText` @@ -18963,257 +29353,296 @@ Create a model response - `:explicit` - - `role: :user | :assistant | :system | :developer` + - `status: :in_progress | :completed | :incomplete` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:user` + - `:in_progress` - - `:assistant` + - `:completed` - - `:system` + - `:incomplete` - - `:developer` + - `type: :function_call_output` - - `phase: :commentary` + The type of the function tool call output. Always `function_call_output`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `:function_call_output` - - `:commentary` + - `agent: Agent{ agent_name}` - - `type: :message` + The agent that produced this item. - The type of the message input. Always `message`. + - `agent_name: String` - - `:message` + The canonical name of the agent that produced this item. - - `class Message` + - `caller_: Direct{ type} | Program{ 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. + The execution context that produced this tool call. - - `content: BetaResponseInputMessageContentList` + - `class Direct` - A list of one or many input items to the model, containing different content - types. + - `type: :direct` - - `role: :user | :system | :developer` + The caller type. Always `direct`. - The role of the message input. One of `user`, `system`, or `developer`. + - `:direct` - - `:user` + - `class Program` - - `:system` + - `caller_id: String` - - `:developer` + The call ID of the program item that produced this tool call. - - `agent: Agent{ 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: String` - - `status: :in_progress | :completed | :incomplete` + The identifier of the actor that created the item. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class AgentMessage` - - `:in_progress` + - `id: String` - - `:completed` + The unique ID of the agent message. - - `:incomplete` + - `author: String` - - `type: :message` + The sending agent identity. - The type of the message input. Always set to `message`. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `:message` + Encrypted content sent between agents. - - `class BetaResponseOutputMessage` + - `class BetaResponseInputText` - An output message from the model. + A text input to the model. - - `id: String` + - `class BetaResponseOutputText` - The unique ID of the output message. + A text output from the model. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `class Text` - The content of the output message. + A text content. - - `class BetaResponseOutputText` + - `text: String` - A text output from the model. + - `type: :text` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `:text` - The annotations of the text output. + - `class SummaryText` - - `class FileCitation` + A summary text from the model. - A citation to a file. + - `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` + + - `class ReasoningText` + + 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` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot` + + A screenshot of a computer. + + - `detail: :low | :high | :auto | :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 ID of the file. + The identifier of an uploaded file that contains the screenshot. - - `filename: String` + - `image_url: String` - The filename of the file cited. + The URL of the screenshot image. - - `index: Integer` + - `type: :computer_screenshot` - The index of the file in the list of files. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `type: :file_citation` + - `:computer_screenshot` - The type of the file citation. Always `file_citation`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:file_citation` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class URLCitation` + - `mode: :explicit` - A citation for a web resource used to generate a model response. + The breakpoint mode. Always `explicit`. - - `end_index: Integer` + - `:explicit` - The index of the last character of the URL citation in the message. + - `class BetaResponseInputFile` - - `start_index: Integer` + A file input to the model. - The index of the first character of the URL citation in the message. + - `class EncryptedContent` - - `title: String` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The title of the web resource. + - `encrypted_content: String` - - `type: :url_citation` + Opaque encrypted content. - The type of the URL citation. Always `url_citation`. + - `type: :encrypted_content` - - `:url_citation` + The type of the input item. Always `encrypted_content`. - - `url: String` + - `:encrypted_content` - The URL of the web resource. + - `recipient: String` - - `class ContainerFileCitation` + The destination agent identity. - A citation for a container file used to generate a model response. + - `type: :agent_message` - - `container_id: String` + The type of the item. Always `agent_message`. - The ID of the container file. + - `:agent_message` - - `end_index: Integer` + - `agent: Agent{ 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` + - `class MultiAgentCall` - The filename of the container file cited. + - `id: String` - - `start_index: Integer` + The unique ID of the multi-agent call item. - The index of the first character of the container file citation in the message. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :container_file_citation` + The multi-agent action to execute. - The type of the container file citation. Always `container_file_citation`. + - `:spawn_agent` - - `:container_file_citation` + - `:interrupt_agent` - - `class FilePath` + - `:list_agents` - A path to a file. + - `:send_message` - - `file_id: String` + - `:followup_task` - The ID of the file. + - `:wait_agent` - - `index: Integer` + - `arguments: String` - The index of the file in the list of files. + The JSON string of arguments generated for the action. - - `type: :file_path` + - `call_id: String` - The type of the file path. Always `file_path`. + The unique ID linking this call to its output. - - `:file_path` + - `type: :multi_agent_call` - - `text: String` + The type of the multi-agent call. Always `multi_agent_call`. - The text output from the model. + - `:multi_agent_call` - - `type: :output_text` + - `agent: Agent{ agent_name}` - The type of the output text. Always `output_text`. + The agent that produced this item. - - `:output_text` + - `agent_name: String` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The canonical name of the agent that produced this item. - - `token: String` + - `class MultiAgentCallOutput` - - `bytes: Array[Integer]` + - `id: String` - - `logprob: Float` + The unique ID of the multi-agent call output item. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `token: String` + The multi-agent action that produced this result. - - `bytes: Array[Integer]` + - `:spawn_agent` - - `logprob: Float` + - `:interrupt_agent` - - `class BetaResponseOutputRefusal` + - `:list_agents` - A refusal from the model. + - `:send_message` - - `refusal: String` + - `:followup_task` - The refusal explanation from the model. + - `:wait_agent` - - `type: :refusal` + - `call_id: String` - The type of the refusal. Always `refusal`. + The unique ID of the multi-agent call. - - `:refusal` + - `output: Array[BetaResponseOutputText]` - - `role: :assistant` + Text output returned by the multi-agent action. - The role of the output message. Always `assistant`. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:assistant` + The annotations of the text output. - - `status: :in_progress | :completed | :incomplete` + - `text: String` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The text output from the model. - - `:in_progress` + - `type: :output_text` - - `:completed` + The type of the output text. Always `output_text`. - - `:incomplete` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `type: :message` + - `type: :multi_agent_call_output` - The type of the output message. Always `message`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `:message` + - `:multi_agent_call_output` - `agent: Agent{ agent_name}` @@ -19223,89 +29652,109 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `class BetaResponseFunctionWebSearch` - 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 results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `:commentary` + - `id: String` - - `class BetaResponseFileSearchToolCall` + The unique ID of the web search tool call. - 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. + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `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 unique ID of the file search tool call. + - `class Search` + + Action type "search" - Performs a web search query. + + - `type: :search` + + The action type. + + - `:search` - `queries: Array[String]` - The queries used to search for files. + The search queries. - - `status: :in_progress | :searching | :completed | 2 more` + - `query: String` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The search query. - - `:in_progress` + - `sources: Array[Source{ type, url}]` - - `:searching` + The sources used in the search. - - `:completed` + - `type: :url` - - `:incomplete` + The type of source. Always `url`. - - `:failed` + - `:url` - - `type: :file_search_call` + - `url: String` - The type of the file search tool call. Always `file_search_call`. + The URL of the source. - - `:file_search_call` + - `class OpenPage` - - `agent: Agent{ agent_name}` + Action type "open_page" - Opens a specific URL from search results. - The agent that produced this item. + - `type: :open_page` - - `agent_name: String` + The action type. - The canonical name of the agent that produced this item. + - `:open_page` - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `url: String` - The results of the file search tool call. + The URL opened by the model. - - `attributes: Hash[Symbol, String | Float | bool]` + - `class FindInPage` - Set of 16 key-value pairs that can be attached to an object. 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. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `String = String` + - `pattern: String` - - `Float = Float` + The pattern or text to search for within the page. - - `UnionMember2 = bool` + - `type: :find_in_page` - - `file_id: String` + The action type. - The unique ID of the file. + - `:find_in_page` - - `filename: String` + - `url: String` - The name of the file. + The URL of the page searched for the pattern. - - `score: Float` + - `status: :in_progress | :searching | :completed | :failed` - The relevance score of the file - a value between 0 and 1. + The status of the web search tool call. - - `text: String` + - `:in_progress` - The text that was retrieved from the file. + - `:searching` + + - `:completed` + + - `:failed` + + - `type: :web_search_call` + + The type of the web search tool call. Always `web_search_call`. + + - `:web_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. - `class BetaResponseComputerToolCall` @@ -19597,9 +30046,11 @@ Create a model response The canonical name of the agent that produced this item. - - `class ComputerCallOutput` + - `class BetaResponseComputerToolCallOutputItem` - The output of a computer tool call. + - `id: String` + + The unique ID of the computer call tool output. - `call_id: String` @@ -19624,19 +30075,29 @@ Create a model response The URL of the screenshot image. + - `status: :completed | :incomplete | :failed | :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` - - `id: String` - - The ID of the computer tool call output. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The safety checks reported by the API that have been acknowledged by the developer. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: String` @@ -19658,146 +30119,40 @@ Create a model response The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :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` + - `created_by: String` - - `:incomplete` + The identifier of the actor that created the item. - - `class BetaResponseFunctionWebSearch` + - `class BetaResponseReasoningItem` - 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 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 ID of the web search tool call. - - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). - - - `class Search` - - Action type "search" - Performs a web search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `query: String` - - The search query. - - - `sources: Array[Source{ type, url}]` - - The sources used in the search. - - - `type: :url` - - The type of source. Always `url`. - - - `:url` - - - `url: String` - - The URL of the source. - - - `class OpenPage` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: :open_page` - - The action type. - - - `:open_page` - - - `url: String` - - The URL opened by the model. - - - `class FindInPage` - - 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 | :searching | :completed | :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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class BetaResponseFunctionToolCall` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - - `arguments: String` + The unique identifier of the reasoning content. - A JSON string of the arguments to pass to the function. + - `summary: Array[Summary{ text, type}]` - - `call_id: String` + Reasoning summary content. - The unique ID of the function tool call generated by the model. + - `text: String` - - `name: String` + A summary of the reasoning output from the model so far. - The name of the function to run. + - `type: :summary_text` - - `type: :function_call` + The type of the object. Always `summary_text`. - The type of the function tool call. Always `function_call`. + - `:summary_text` - - `:function_call` + - `type: :reasoning` - - `id: String` + The type of the object. Always `reasoning`. - The unique ID of the function tool call. + - `:reasoning` - `agent: Agent{ agent_name}` @@ -19807,29 +30162,24 @@ Create a model response The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` + - `content: Array[Content{ text, type}]` - - `:direct` + Reasoning text content. - - `class Program` + - `text: String` - - `caller_id: String` + The reasoning text from the model. - The call ID of the program item that produced this tool call. + - `type: :reasoning_text` - - `type: :program` + The type of the reasoning text. Always `reasoning_text`. - - `:program` + - `:reasoning_text` - - `namespace: String` + - `encrypted_content: String` - The namespace of the function to run. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: :in_progress | :completed | :incomplete` @@ -19842,236 +30192,30 @@ Create a model response - `:incomplete` - - `class FunctionCallOutput` - - The output of a function tool call. - - - `call_id: String` - - The unique ID of the function tool call generated by the model. - - - `output: String | BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `String = String` - - A JSON string of the output of the function tool call. - - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - An array of content outputs (text, image, file) for the function tool call. - - - `class BetaResponseInputTextContent` - - 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: PromptCacheBreakpoint{ 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` - - - `class BetaResponseInputImageContent` - - 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`. - - - `:input_image` - - - `detail: :low | :high | :auto | :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: String` - - The ID of the file to be sent to the model. - - - `image_url: 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: PromptCacheBreakpoint{ 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` - - - `class BetaResponseInputFileContent` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` - - The base64-encoded data of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` + - `class Program` - `id: String` - The unique ID of the function tool call output. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` + The unique ID of the program item. - - `type: :direct` + - `call_id: String` - The caller type. Always `direct`. + The stable call ID of the program item. - - `:direct` + - `code: String` - - `class Program` + The JavaScript source executed by programmatic tool calling. - - `caller_id: String` + - `fingerprint: String` - The call ID of the program item that produced this tool call. + Opaque program replay fingerprint that must be round-tripped. - `type: :program` - The caller type. Always `program`. + The type of the item. Always `program`. - `:program` - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class AgentMessage` - - A message routed between agents. - - - `author: String` - - The sending agent identity. - - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - Plaintext, image, or encrypted content sent between agents. - - - `class BetaResponseInputTextContent` - - A text input to the model. - - - `class BetaResponseInputImageContent` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `class EncryptedContent` - - 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: String` - - The unique ID of this agent message item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -20080,41 +30224,33 @@ Create a model response The canonical name of the agent that produced this item. - - `class MultiAgentCall` - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action that was executed. - - - `:spawn_agent` - - - `:interrupt_agent` + - `class ProgramOutput` - - `: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 | :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: String` + The type of the item. Always `program_output`. - The unique ID of this multi-agent call. + - `:program_output` - `agent: Agent{ agent_name}` @@ -20124,127 +30260,43 @@ Create a model response The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput` - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action that produced this result. - - - `:spawn_agent` - - - `:interrupt_agent` + - `class BetaResponseToolSearchCall` - - `:list_agents` + - `id: String` - - `:send_message` + The unique ID of the tool search call item. - - `:followup_task` + - `arguments: untyped` - - `:wait_agent` + Arguments used for the tool search call. - `call_id: String` - The unique ID of the multi-agent call. - - - `output: Array[Output{ 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: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - Citations associated with the text content. - - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - - `file_id: String` - - The ID of the file. - - - `filename: String` - - The filename of the file cited. - - - `index: Integer` - - The index of the file in the list of files. - - - `type: :file_citation` - - The citation type. Always `file_citation`. - - - `:file_citation` - - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - - `end_index: Integer` - - The index of the last character of the citation in the message. - - - `start_index: Integer` - - 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. - - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - - `container_id: String` - - The ID of the container. - - - `end_index: Integer` - - 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 | :client` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `start_index: Integer` + - `:server` - The index of the first character of the citation in the message. + - `:client` - - `type: :container_file_citation` + - `status: :in_progress | :completed | :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: String` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `:tool_search_call` - `agent: Agent{ agent_name}` @@ -20254,29 +30306,15 @@ Create a model response The canonical name of the agent that produced this item. - - `class ToolSearchCall` - - - `arguments: untyped` - - The arguments supplied to the tool search call. - - - `type: :tool_search_call` + - `created_by: String` - The item type. Always `tool_search_call`. + The identifier of the actor that created the item. - - `:tool_search_call` + - `class BetaResponseToolSearchOutputItem` - `id: String` - The unique ID of this tool search call. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - `call_id: String` @@ -20292,7 +30330,7 @@ Create a model response - `status: :in_progress | :completed | :incomplete` - The status of the tool search call. + The status of the tool search output item that was recorded. - `:in_progress` @@ -20300,11 +30338,9 @@ Create a model response - `:incomplete` - - `class BetaResponseToolSearchOutputItemParam` - - `tools: Array[BetaTool]` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool` @@ -20403,7 +30439,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -20413,7 +30449,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -20460,7 +30500,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -20470,7 +30510,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -21394,14 +31438,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: String` - - The unique ID of this tool search output. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -21410,39 +31450,39 @@ Create a model response The canonical name of the agent that produced this item. - - `call_id: String` - - The unique ID of the tool search call generated by the model. + - `created_by: String` - - `execution: :server | :client` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `class AdditionalTools` - - `:server` + - `id: String` - - `:client` + The unique ID of the additional tools item. - - `status: :in_progress | :completed | :incomplete` + - `role: :unknown | :user | :assistant | 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `:in_progress` + - `:unknown` - - `:completed` + - `:user` - - `:incomplete` + - `:assistant` - - `class AdditionalTools` + - `:system` - - `role: :developer` + - `:critic` - The role that provided the additional tools. Only `developer` is supported. + - `:discriminator` - `:developer` + - `:tool` + - `tools: Array[BetaTool]` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `class BetaFunctionTool` @@ -21510,14 +31550,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: String` - - The unique ID of this additional tools item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -21526,82 +31562,17 @@ Create a model response The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem` + - `class BetaResponseCompactionItem` - 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](https://platform.openai.com/docs/api-reference/responses/compact). - `id: String` - The unique identifier of the reasoning content. - - - `summary: Array[Summary{ 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `content: Array[Content{ 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: String` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class BetaResponseCompactionItemParam` - - 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` @@ -21609,10 +31580,6 @@ Create a model response - `:compaction` - - `id: String` - - The ID of the compaction item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -21621,6 +31588,10 @@ Create a model response The canonical name of the agent that produced this item. + - `created_by: String` + + The identifier of the actor that created the item. + - `class ImageGenerationCall` An image generation request made by the model. @@ -21838,9 +31809,13 @@ Create a model response - `:incomplete` - - `class ShellCall` + - `class BetaResponseFunctionShellToolCall` - 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: Action{ commands, max_output_length, timeout_ms}` @@ -21848,30 +31823,60 @@ Create a model response - `commands: Array[String]` - Ordered shell commands for the execution environment to run. - - `max_output_length: Integer` - 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: Integer` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: String` The unique ID of the shell tool call generated by the model. + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment` + + Represents the use of a local environment to perform shell actions. + + - `type: :local` + + The environment type. Always `local`. + + - `:local` + + - `class BetaResponseContainerReference` + + Represents a container created with /v1/containers. + + - `container_id: String` + + - `type: :container_reference` + + The environment type. Always `container_reference`. + + - `:container_reference` + + - `status: :in_progress | :completed | :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: String` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -21888,8 +31893,6 @@ Create a model response - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -21900,43 +31903,35 @@ Create a model response - `type: :program` - The caller type. Always `program`. - - `:program` - - `environment: BetaLocalEnvironment | BetaContainerReference` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment` - - - `class BetaContainerReference` - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: String` - - `:in_progress` + The ID of the entity that created this tool call. - - `:completed` + - `class BetaResponseFunctionShellToolCallOutput` - - `:incomplete` + The output of a shell tool call that was emitted. - - `class ShellCallOutput` + - `id: String` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: String` The unique ID of the shell tool call generated by the model. - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + - `max_output_length: Integer` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + + An array of shell call output contents - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `class Timeout` @@ -21954,7 +31949,7 @@ Create a model response - `exit_code: Integer` - The exit code returned by the shell process. + Exit code from the shell process. - `type: :exit` @@ -21964,21 +31959,31 @@ Create a model response - `stderr: String` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: String` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: :shell_call_output` + - `created_by: String` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `:shell_call_output` + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :shell_call_output` + + The type of the shell call output. Always `shell_call_output`. + + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -21996,8 +32001,6 @@ Create a model response - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -22008,27 +32011,19 @@ Create a model response - `type: :program` - The caller type. Always `program`. - - `:program` - - `max_output_length: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call output. + - `created_by: String` - - `:in_progress` + The identifier of the actor that created the item. - - `:completed` + - `class BetaResponseApplyPatchToolCall` - - `:incomplete` + A tool call that applies file diffs by creating, deleting, or updating files. - - `class ApplyPatchCall` + - `id: String` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: String` @@ -22036,55 +32031,55 @@ Create a model response - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `class CreateFile` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: String` - Unified diff content to apply when creating the file. + Diff to apply. - `path: String` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: :create_file` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `:create_file` - `class DeleteFile` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: String` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: :delete_file` - The operation type. Always `delete_file`. + Delete the specified file. - `:delete_file` - `class UpdateFile` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: String` - Unified diff content to apply to the existing file. + Diff to apply. - `path: String` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: :update_file` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `:update_file` @@ -22102,10 +32097,6 @@ Create a model response - `:apply_patch_call` - - `id: String` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -22122,8 +32113,6 @@ Create a model response - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -22134,13 +32123,19 @@ Create a model response - `type: :program` - The caller type. Always `program`. - - `:program` - - `class ApplyPatchCallOutput` + - `created_by: String` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + 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` @@ -22160,10 +32155,6 @@ Create a model response - `:apply_patch_call_output` - - `id: String` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -22180,8 +32171,6 @@ Create a model response - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -22192,13 +32181,76 @@ Create a model response - `type: :program` - The caller type. Always `program`. - - `:program` + - `created_by: String` + + The ID of the entity that created this tool call output. + - `output: String` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. + + - `class McpCall` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_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. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` - `class McpListTools` @@ -22288,6 +32340,10 @@ Create a model response 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. @@ -22302,10 +32358,6 @@ Create a model response - `:mcp_approval_response` - - `id: String` - - The unique ID of the approval response - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -22318,31 +32370,31 @@ Create a model response Optional reason for the decision. - - `class McpCall` + - `class BetaResponseCustomToolCall` - An invocation of a tool on an MCP server. + A call to a custom tool created by the model. - - `id: String` + - `call_id: String` - The unique ID of the tool call. + An identifier used to map this custom tool call to a tool call output. - - `arguments: String` + - `input: String` - A JSON string of the arguments passed to the tool. + The input for the custom tool call generated by the model. - `name: String` - The name of the tool that was run. + The name of the custom tool being called. - - `server_label: String` + - `type: :custom_tool_call` - The label of the MCP server running the tool. + The type of the custom tool call. Always `custom_tool_call`. - - `type: :mcp_call` + - `:custom_tool_call` - The type of the item. Always `mcp_call`. + - `id: String` - - `:mcp_call` + The unique ID of the custom tool call in the OpenAI platform. - `agent: Agent{ agent_name}` @@ -22352,22 +32404,42 @@ Create a model response The canonical name of the agent that produced this item. - - `approval_request_id: String` + - `caller_: Direct{ type} | Program{ 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: String` + - `class Direct` - The error from the tool call, if any. + - `type: :direct` - - `output: String` + - `:direct` - The output from the tool call. + - `class Program` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `caller_id: String` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class BetaResponseCustomToolCallOutputItem` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: String` + + The unique ID of the custom tool call output item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -22375,242 +32447,347 @@ Create a model response - `:incomplete` - - `:calling` + - `created_by: String` - - `:failed` + The identifier of the actor that created the item. - - `class BetaResponseCustomToolCallOutput` + - `usage: BetaResponseUsage` - The output of a custom tool call from your code, being sent back to the model. + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - `call_id: String` + - `input_tokens: Integer` - The call ID, used to map this custom tool call output to a custom tool call. + The number of input tokens. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A detailed breakdown of the input tokens. - - `String = String` + - `cache_write_tokens: Integer` - A string of the output of the custom tool call. + The number of input tokens that were written to the cache. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `cached_tokens: Integer` - Text, image, or file output of the 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). - - `class BetaResponseInputText` + - `output_tokens: Integer` - A text input to the model. + The number of output tokens. - - `class BetaResponseInputImage` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A detailed breakdown of the output tokens. - - `class BetaResponseInputFile` + - `reasoning_tokens: Integer` - A file input to the model. + The number of reasoning tokens. - - `type: :custom_tool_call_output` + - `total_tokens: Integer` - The type of the custom tool call output. Always `custom_tool_call_output`. + The total number of tokens used. - - `:custom_tool_call_output` +### Example - - `id: String` +```ruby +require "openai" - The unique ID of the custom tool call output in the OpenAI platform. +openai = OpenAI::Client.new(api_key: "My API Key") - - `agent: Agent{ agent_name}` +beta_compacted_response = openai.beta.responses.compact(model: :"gpt-5.6-sol") - The agent that produced this item. +puts(beta_compacted_response) +``` - - `agent_name: String` +#### Response - The canonical name of the agent that produced this item. +```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_: Direct{ type} | Program{ caller_id, type}` +## Domain Types - The execution context that produced this tool call. +### Beta Apply Patch Tool - - `class Direct` +- `class BetaApplyPatchTool` - - `type: :direct` + Allows the assistant to create, delete, or update files using unified diffs. - The caller type. Always `direct`. + - `type: :apply_patch` - - `:direct` + The type of the tool. Always `apply_patch`. - - `class Program` + - `:apply_patch` - - `caller_id: String` + - `allowed_callers: Array[:direct | :programmatic]` - The call ID of the program item that produced this tool call. + The tool invocation context(s). - - `type: :program` + - `:direct` - The caller type. Always `program`. + - `:programmatic` - - `:program` +### Beta Compacted Response - - `class BetaResponseCustomToolCall` +- `class BetaCompactedResponse` - A call to a custom tool created by the model. + - `id: String` - - `call_id: String` + The unique identifier for the compacted response. - An identifier used to map this custom tool call to a tool call output. + - `created_at: Integer` - - `input: String` + Unix timestamp (in seconds) when the compacted conversation was created. - The input for the custom tool call generated by the model. + - `object: :"response.compaction"` - - `name: String` + The object type. Always `response.compaction`. - The name of the custom tool being called. + - `:"response.compaction"` - - `type: :custom_tool_call` + - `output: Array[BetaResponseOutputItem]` - The type of the custom tool call. Always `custom_tool_call`. + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - - `:custom_tool_call` + - `class BetaResponseOutputMessage` + + An output message from the model. - `id: String` - The unique ID of the custom tool call in the OpenAI platform. + The unique ID of the output message. - - `agent: Agent{ agent_name}` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The agent that produced this item. + The content of the output message. - - `agent_name: String` + - `class BetaResponseOutputText` - The canonical name of the agent that produced this item. + A text output from the model. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - The execution context that produced this tool call. + The annotations of the text output. - - `class Direct` + - `class FileCitation` - - `type: :direct` + A citation to a file. - - `:direct` + - `file_id: String` - - `class Program` + The ID of the file. - - `caller_id: String` + - `filename: String` - The call ID of the program item that produced this tool call. + The filename of the file cited. - - `type: :program` + - `index: Integer` - - `:program` + The index of the file in the list of files. - - `namespace: String` + - `type: :file_citation` - The namespace of the custom tool being called. + The type of the file citation. Always `file_citation`. - - `class CompactionTrigger` + - `:file_citation` - Compacts the current context. Must be the final input item. + - `class URLCitation` - - `type: :compaction_trigger` + A citation for a web resource used to generate a model response. - The type of the item. Always `compaction_trigger`. + - `end_index: Integer` - - `:compaction_trigger` + The index of the last character of the URL citation in the message. - - `agent: Agent{ agent_name}` + - `start_index: Integer` - The agent that produced this item. + The index of the first character of the URL citation in the message. - - `agent_name: String` + - `title: String` - The canonical name of the agent that produced this item. + The title of the web resource. - - `class ItemReference` + - `type: :url_citation` - An internal identifier for an item to reference. + The type of the URL citation. Always `url_citation`. - - `id: String` + - `:url_citation` - The ID of the item to reference. + - `url: String` - - `agent: Agent{ agent_name}` + The URL of the web resource. - The agent that produced this item. + - `class ContainerFileCitation` - - `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` - - `type: :item_reference` + The ID of the container file. - The type of item to reference. Always `item_reference`. + - `end_index: Integer` + + 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: Integer` + + 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` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `:file_path` - - `:item_reference` + - `text: String` - - `class Program` + The text output from the model. - - `id: String` + - `type: :output_text` - The unique ID of this program item. + The type of the output text. Always `output_text`. - - `call_id: String` + - `:output_text` - The stable call ID of the program item. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `code: String` + - `token: String` - The JavaScript source executed by programmatic tool calling. + - `bytes: Array[Integer]` - - `fingerprint: String` + - `logprob: Float` - Opaque program replay fingerprint that must be round-tripped. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `type: :program` + - `token: String` - The item type. Always `program`. + - `bytes: Array[Integer]` - - `:program` + - `logprob: Float` - - `agent: Agent{ agent_name}` + - `class BetaResponseOutputRefusal` - 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. - - `class ProgramOutput` + - `type: :refusal` - - `id: String` + The type of the refusal. Always `refusal`. - The unique ID of this program output item. + - `:refusal` - - `call_id: String` + - `role: :assistant` - The call ID of the program item. + The role of the output message. Always `assistant`. - - `result: String` + - `:assistant` - The result produced by the program item. + - `status: :in_progress | :completed | :incomplete` - - `status: :completed | :incomplete` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The terminal status of the program output. + - `:in_progress` - `:completed` - `:incomplete` - - `type: :program_output` + - `type: :message` - The item type. Always `program_output`. + The type of the output message. Always `message`. - - `:program_output` + - `:message` - `agent: Agent{ agent_name}` @@ -22620,286 +32797,294 @@ Create a model response The canonical name of the agent that produced this item. - - `metadata: Hash[Symbol, String]` + - `phase: :commentary | :final_answer` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + 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. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:commentary` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `:final_answer` - 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. + - `class BetaResponseFileSearchToolCall` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 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. - 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. + - `id: String` - - `:"gpt-5.6-sol"` + The unique ID of the file search tool call. - - `:"gpt-5.6-terra"` + - `queries: Array[String]` - - `:"gpt-5.6-luna"` + The queries used to search for files. - - `:"gpt-5.4"` + - `status: :in_progress | :searching | :completed | 2 more` - - `:"gpt-5.4-mini"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `:"gpt-5.4-nano"` + - `:in_progress` - - `:"gpt-5.4-mini-2026-03-17"` + - `:searching` - - `:"gpt-5.4-nano-2026-03-17"` + - `:completed` - - `:"gpt-5.3-chat-latest"` + - `:incomplete` - - `:"gpt-5.2"` + - `:failed` - - `:"gpt-5.2-2025-12-11"` + - `type: :file_search_call` - - `:"gpt-5.2-chat-latest"` + The type of the file search tool call. Always `file_search_call`. - - `:"gpt-5.2-pro"` + - `:file_search_call` - - `:"gpt-5.2-pro-2025-12-11"` + - `agent: Agent{ agent_name}` - - `:"gpt-5.1"` + The agent that produced this item. - - `:"gpt-5.1-2025-11-13"` + - `agent_name: String` - - `:"gpt-5.1-codex"` + The canonical name of the agent that produced this item. - - `:"gpt-5.1-mini"` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - `:"gpt-5.1-chat-latest"` + The results of the file search tool call. - - `:"gpt-5"` + - `attributes: Hash[Symbol, String | Float | bool]` - - `:"gpt-5-mini"` + Set of 16 key-value pairs that can be attached to an object. 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. - - `:"gpt-5-nano"` + - `String = String` - - `:"gpt-5-2025-08-07"` + - `Float = Float` - - `:"gpt-5-mini-2025-08-07"` + - `UnionMember2 = bool` - - `:"gpt-5-nano-2025-08-07"` + - `file_id: String` - - `:"gpt-5-chat-latest"` + The unique ID of the file. - - `:"gpt-4.1"` + - `filename: String` - - `:"gpt-4.1-mini"` + The name of the file. - - `:"gpt-4.1-nano"` + - `score: Float` - - `:"gpt-4.1-2025-04-14"` + The relevance score of the file - a value between 0 and 1. - - `:"gpt-4.1-mini-2025-04-14"` + - `text: String` - - `:"gpt-4.1-nano-2025-04-14"` + The text that was retrieved from the file. - - `:"o4-mini"` + - `class BetaResponseFunctionToolCall` - - `:"o4-mini-2025-04-16"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:o3` + - `arguments: String` - - `:"o3-2025-04-16"` + A JSON string of the arguments to pass to the function. - - `:"o3-mini"` + - `call_id: String` - - `:"o3-mini-2025-01-31"` + The unique ID of the function tool call generated by the model. - - `:o1` + - `name: String` - - `:"o1-2024-12-17"` + The name of the function to run. - - `:"o1-preview"` + - `type: :function_call` - - `:"o1-preview-2024-09-12"` + The type of the function tool call. Always `function_call`. - - `:"o1-mini"` + - `:function_call` - - `:"o1-mini-2024-09-12"` + - `id: String` - - `:"gpt-4o"` + The unique ID of the function tool call. - - `:"gpt-4o-2024-11-20"` + - `agent: Agent{ 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"` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:"gpt-4o-audio-preview-2024-12-17"` + The execution context that produced this tool call. - - `:"gpt-4o-audio-preview-2025-06-03"` + - `class Direct` - - `:"gpt-4o-mini-audio-preview"` + - `type: :direct` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `:direct` - - `:"gpt-4o-search-preview"` + - `class Program` - - `:"gpt-4o-mini-search-preview"` + - `caller_id: String` - - `:"gpt-4o-search-preview-2025-03-11"` + The call ID of the program item that produced this tool call. - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `type: :program` - - `:"chatgpt-4o-latest"` + - `:program` - - `:"codex-mini-latest"` + - `namespace: String` - - `:"gpt-4o-mini"` + The namespace of the function to run. - - `:"gpt-4o-mini-2024-07-18"` + - `status: :in_progress | :completed | :incomplete` - - `:"gpt-4-turbo"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:"gpt-4-turbo-2024-04-09"` + - `:in_progress` - - `:"gpt-4-0125-preview"` + - `:completed` - - `:"gpt-4-turbo-preview"` + - `:incomplete` - - `:"gpt-4-1106-preview"` + - `class BetaResponseFunctionToolCallOutputItem` - - `:"gpt-4-vision-preview"` + - `id: String` - - `:"gpt-4"` + The unique ID of the function call tool output. - - `:"gpt-4-0314"` + - `call_id: String` - - `:"gpt-4-0613"` + The unique ID of the function tool call generated by the model. - - `:"gpt-4-32k"` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:"gpt-4-32k-0314"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:"gpt-4-32k-0613"` + - `String = String` - - `:"gpt-3.5-turbo"` + A string of the output of the function call. - - `:"gpt-3.5-turbo-16k"` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:"gpt-3.5-turbo-0301"` + Text, image, or file output of the function call. - - `:"gpt-3.5-turbo-0613"` + - `class BetaResponseInputText` - - `:"gpt-3.5-turbo-1106"` + A text input to the model. - - `:"gpt-3.5-turbo-0125"` + - `text: String` - - `:"gpt-3.5-turbo-16k-0613"` + The text input to the model. - - `:"o1-pro"` + - `type: :input_text` - - `:"o1-pro-2025-03-19"` + The type of the input item. Always `input_text`. - - `:"o3-pro"` + - `:input_text` - - `:"o3-pro-2025-06-10"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:"o3-deep-research"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:"o3-deep-research-2025-06-26"` + - `mode: :explicit` - - `:"o4-mini-deep-research"` + The breakpoint mode. Always `explicit`. - - `:"o4-mini-deep-research-2025-06-26"` + - `:explicit` - - `:"computer-use-preview"` + - `class BetaResponseInputImage` - - `:"computer-use-preview-2025-03-11"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:"gpt-5-codex"` + - `detail: :low | :high | :auto | :original` - - `:"gpt-5-pro"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:"gpt-5-pro-2025-10-06"` + - `:low` - - `:"gpt-5.1-codex-max"` + - `:high` - - `String = String` + - `:auto` - - `object: :response` + - `:original` - The object type of this resource - always set to `response`. + - `type: :input_image` - - `:response` + The type of the input item. Always `input_image`. - - `output: Array[BetaResponseOutputItem]` + - `:input_image` - An array of content items generated by the model. + - `file_id: 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 ID of the file to be sent to the model. - - `class BetaResponseOutputMessage` + - `image_url: String` - An output message from the model. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class BetaResponseFileSearchToolCall` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - 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. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseFunctionToolCall` + - `mode: :explicit` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The breakpoint mode. Always `explicit`. - - `class BetaResponseFunctionToolCallOutputItem` + - `:explicit` - - `id: String` + - `class BetaResponseInputFile` - The unique ID of the function call tool output. + A file input to the model. - - `call_id: String` + - `type: :input_file` - The unique ID of the function tool call generated by the model. + The type of the input item. Always `input_file`. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:input_file` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `detail: :auto | :low | :high` - - `String = 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`. - A string of the output of the function call. + - `:auto` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:low` - Text, image, or file output of the function call. + - `:high` - - `class BetaResponseInputText` + - `file_data: String` - A text input to the model. + The content of the file to be sent to the model. - - `class BetaResponseInputImage` + - `file_id: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The ID of the file to be sent to the model. - - `class BetaResponseInputFile` + - `file_url: String` - A file input to the model. + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 | :completed | :incomplete` @@ -23205,11 +33390,395 @@ Create a model response 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: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). + + - `class Search` + + Action type "search" - Performs a web search query. + + - `type: :search` + + The action type. + + - `:search` + + - `queries: Array[String]` + + The search queries. + + - `query: String` + + The search query. + + - `sources: Array[Source{ type, url}]` + + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` + + - `url: String` + + The URL of the source. + + - `class OpenPage` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: :open_page` + + The action type. + + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + 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 | :searching | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + - `class BetaResponseComputerToolCall` 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[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :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: BetaComputerAction` + + A click action. + + - `class Click` + + A click action. + + - `button: :left | :right | :wheel | 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: Integer` + + The x-coordinate where the click occurred. + + - `y_: Integer` + + The y-coordinate where the click occurred. + + - `keys: Array[String]` + + The keys being held while clicking. + + - `class DoubleClick` + + A double click action. + + - `keys: Array[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: Integer` + + The x-coordinate where the double click occurred. + + - `y_: Integer` + + The y-coordinate where the double click occurred. + + - `class Drag` + + A drag action. + + - `path: Array[Path{ 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: Integer` + + The x-coordinate. + + - `y_: Integer` + + The y-coordinate. + + - `type: :drag` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `:drag` + + - `keys: Array[String]` + + The keys being held while dragging the mouse. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `keys: Array[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` + + - `class Move` + + A mouse move action. + + - `type: :move` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `:move` + + - `x: Integer` + + The x-coordinate to move to. + + - `y_: Integer` + + The y-coordinate to move to. + + - `keys: Array[String]` + + The keys being held while moving the mouse. + + - `class Screenshot` + + A screenshot action. + + - `type: :screenshot` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `:screenshot` + + - `class Scroll` + + A scroll action. + + - `scroll_x: Integer` + + The horizontal scroll distance. + + - `scroll_y: Integer` + + The vertical scroll distance. + + - `type: :scroll` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class 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` + + - `class Wait` + + A wait action. + + - `type: :wait` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `:wait` + + - `actions: BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click` + + A click action. + + - `class DoubleClick` + + A double click action. + + - `class Drag` + + A drag action. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `class Move` + + A mouse move action. + + - `class Screenshot` + + A screenshot action. + + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + - `class BetaResponseComputerToolCallOutputItem` - `id: String` @@ -23224,6 +33793,21 @@ Create a model response 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: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: String` + + The URL of the screenshot image. + - `status: :completed | :incomplete | :failed | :in_progress` The status of the message input. One of `in_progress`, `completed`, or @@ -23279,6 +33863,68 @@ Create a model response 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[Summary{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ 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: String` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + - `class Program` - `id: String` @@ -23433,1152 +34079,1143 @@ Create a model response Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class BetaFileSearchTool` - - 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). - - - `class BetaComputerTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool` - - 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). - - - `class Mcp` - - 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). - - - `class CodeInterpreter` - - A tool that runs Python code to help generate a response to a prompt. - - - `class ProgrammaticToolCalling` + - `name: String` - - `class ImageGeneration` + The name of the function to call. - A tool that generates images using the GPT image models. + - `parameters: Hash[Symbol, untyped]` - - `class LocalShell` + A JSON schema object describing the parameters of the function. - A tool that allows the model to execute shell commands in a local environment. + - `strict: bool` - - `class BetaFunctionShellTool` + Whether strict parameter validation is enforced for this function tool. - A tool that allows the model to execute shell commands. + - `type: :function` - - `class BetaCustomTool` + The type of the function tool. Always `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) + - `:function` - - `class BetaNamespaceTool` + - `allowed_callers: Array[:direct | :programmatic]` - Groups function/custom tools under a shared namespace. + The tool invocation context(s). - - `class BetaToolSearchTool` + - `:direct` - Hosted or BYOT tool search configuration for deferred tools. + - `:programmatic` - - `class BetaWebSearchPreviewTool` + - `defer_loading: bool` - 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). + Whether this function is deferred and loaded via tool search. - - `class BetaApplyPatchTool` + - `description: String` - Allows the assistant to create, delete, or update files using unified diffs. + A description of the function. Used by the model to determine whether or not to call the function. - - `type: :tool_search_output` + - `output_schema: Hash[Symbol, untyped]` - The type of the item. Always `tool_search_output`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `:tool_search_output` + - `class BetaFileSearchTool` - - `agent: Agent{ 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` - - `created_by: String` + - `vector_store_ids: Array[String]` - The identifier of the actor that created the item. + The IDs of the vector stores to search. - - `class AdditionalTools` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `id: String` + A filter to apply. - The unique ID of the additional tools item. + - `class ComparisonFilter` - - `role: :unknown | :user | :assistant | 5 more` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The role that provided the additional tools. + - `key: String` - - `:unknown` + The key to compare against the value. - - `:user` + - `type: :eq | :ne | :gt | 5 more` - - `:assistant` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:system` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `:critic` + - `:eq` - - `:discriminator` + - `:ne` - - `:developer` + - `:gt` - - `:tool` + - `:gte` - - `tools: Array[BetaTool]` + - `:lt` - The additional tool definitions made available at this item. + - `:lte` - - `class BetaFunctionTool` + - `:in` - 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). + - `:nin` - - `class BetaFileSearchTool` + - `value: String | Float | bool | Array[String | Float]` - 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 value to compare against the attribute key; supports string, number, or boolean types. - - `class BetaComputerTool` + - `String = String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Float = Float` - - `class BetaComputerUsePreviewTool` + - `UnionMember2 = bool` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `UnionMember3 = Array[String | Float]` - - `class BetaWebSearchTool` + - `String = 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). + - `Float = Float` - - `class Mcp` + - `class CompoundFilter` - 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). + Combine multiple filters using `and` or `or`. - - `class CodeInterpreter` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - A tool that runs Python code to help generate a response to a prompt. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `class ProgrammaticToolCalling` + - `class ComparisonFilter` - - `class ImageGeneration` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A tool that generates images using the GPT image models. + - `key: String` - - `class LocalShell` + The key to compare against the value. - A tool that allows the model to execute shell commands in a local environment. + - `type: :eq | :ne | :gt | 5 more` - - `class BetaFunctionShellTool` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A tool that allows the model to execute shell commands. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class BetaCustomTool` + - `:eq` - 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) + - `:ne` - - `class BetaNamespaceTool` + - `:gt` - Groups function/custom tools under a shared namespace. + - `:gte` - - `class BetaToolSearchTool` + - `:lt` - Hosted or BYOT tool search configuration for deferred tools. + - `:lte` - - `class BetaWebSearchPreviewTool` + - `:in` - 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). + - `:nin` - - `class BetaApplyPatchTool` + - `value: String | Float | bool | Array[String | Float]` - Allows the assistant to create, delete, or update files using unified diffs. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: :additional_tools` + - `String = String` - The type of the item. Always `additional_tools`. + - `Float = Float` - - `:additional_tools` + - `UnionMember2 = bool` - - `agent: Agent{ agent_name}` + - `UnionMember3 = Array[String | Float]` - The agent that produced this item. + - `String = String` - - `agent_name: String` + - `Float = Float` - The canonical name of the agent that produced this item. + - `UnionMember1 = untyped` - - `class BetaResponseCompactionItem` + - `type: :and | :or` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Type of operation: `and` or `or`. - - `id: String` + - `:and` - The unique ID of the compaction item. + - `:or` - - `encrypted_content: String` + - `max_num_results: Integer` - The encrypted content that was produced by compaction. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: :compaction` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The type of the item. Always `compaction`. + Ranking options for search. - - `:compaction` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `agent: Agent{ agent_name}` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The agent that produced this item. + - `embedding_weight: Float` - - `agent_name: String` + The weight of the embedding in the reciprocal ranking fusion. - The canonical name of the agent that produced this item. + - `text_weight: Float` - - `created_by: String` + The weight of the text in the reciprocal ranking fusion. - The identifier of the actor that created the item. + - `ranker: :auto | :"default-2024-11-15"` - - `class ImageGenerationCall` + The ranker to use for the file search. - An image generation request made by the model. + - `:auto` - - `id: String` + - `:"default-2024-11-15"` - The unique ID of the image generation call. + - `score_threshold: Float` - - `result: 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 generated image encoded in base64. + - `class BetaComputerTool` - - `status: :in_progress | :completed | :generating | :failed` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The status of the image generation call. + - `type: :computer` - - `:in_progress` + The type of the computer tool. Always `computer`. - - `:completed` + - `:computer` - - `:generating` + - `class BetaComputerUsePreviewTool` - - `:failed` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :image_generation_call` + - `display_height: Integer` - The type of the image generation call. Always `image_generation_call`. + The height of the computer display. - - `:image_generation_call` + - `display_width: Integer` - - `agent: Agent{ agent_name}` + The width of the computer display. - The agent that produced this item. + - `environment: :windows | :mac | :linux | 2 more` - - `agent_name: String` + The type of computer environment to control. - The canonical name of the agent that produced this item. + - `:windows` - - `class BetaResponseCodeInterpreterToolCall` + - `:mac` - A tool call to run code. + - `:linux` - - `class LocalShellCall` + - `:ubuntu` - A tool call to run a command on the local shell. + - `:browser` - - `id: String` + - `type: :computer_use_preview` - The unique ID of the local shell call. + The type of the computer use tool. Always `computer_use_preview`. - - `action: Action{ command, env, type, 3 more}` + - `:computer_use_preview` - Execute a shell command on the server. + - `class BetaWebSearchTool` - - `command: Array[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 command to run. + - `type: :web_search | :web_search_2025_08_26` - - `env: Hash[Symbol, String]` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Environment variables to set for the command. + - `:web_search` - - `type: :exec` + - `:web_search_2025_08_26` - The type of the local shell action. Always `exec`. + - `filters: Filters{ allowed_domains}` - - `:exec` + Filters for the search. - - `timeout_ms: Integer` + - `allowed_domains: Array[String]` - Optional timeout in milliseconds for the command. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `user: String` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Optional user to run the command as. + - `search_context_size: :low | :medium | :high` - - `working_directory: 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. - Optional working directory to run the command in. + - `:low` - - `call_id: String` + - `:medium` - The unique ID of the local shell tool call generated by the model. + - `:high` - - `status: :in_progress | :completed | :incomplete` + - `user_location: UserLocation{ city, country, region, 2 more}` - The status of the local shell call. + The approximate location of the user. - - `:in_progress` + - `city: String` - - `:completed` + Free text input for the city of the user, e.g. `San Francisco`. - - `:incomplete` + - `country: String` - - `type: :local_shell_call` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The type of the local shell call. Always `local_shell_call`. + - `region: String` - - `:local_shell_call` + Free text input for the region of the user, e.g. `California`. - - `agent: Agent{ agent_name}` + - `timezone: 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: :approximate` - The canonical name of the agent that produced this item. + The type of location approximation. Always `approximate`. - - `class LocalShellCallOutput` + - `:approximate` - The output of a local shell tool call. + - `class Mcp` - - `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 local shell tool call generated by the model. + - `server_label: String` - - `output: String` + A label for this MCP server, used to identify it in tool calls. - A JSON string of the output of the local shell tool call. + - `type: :mcp` - - `type: :local_shell_call_output` + The type of the MCP tool. Always `mcp`. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `:mcp` - - `:local_shell_call_output` + - `allowed_callers: Array[:direct | :programmatic]` - - `agent: Agent{ 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: Array[String] | McpToolFilter{ read_only, tool_names}` - - `status: :in_progress | :completed | :incomplete` + List of allowed tool names or a filter object. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `McpAllowedTools = Array[String]` - - `:in_progress` + A string array of allowed tool names - - `:completed` + - `class McpToolFilter` - - `:incomplete` + A filter object to specify which tools are allowed. - - `class BetaResponseFunctionShellToolCall` + - `read_only: bool` - A tool call that executes one or more shell commands in a managed environment. + Indicates whether or not a tool modifies data or is read-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: Array[String]` - The unique ID of the shell tool call. Populated when this item is returned via API. + List of allowed tool names. - - `action: Action{ commands, max_output_length, timeout_ms}` + - `authorization: String` - The shell commands and limits that describe how to run the 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. - - `commands: Array[String]` + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `max_output_length: Integer` + 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). - Optional maximum number of characters to return from each command. + Currently supported `connector_id` values are: - - `timeout_ms: Integer` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - Optional timeout in milliseconds for the commands. + - `:connector_dropbox` - - `call_id: String` + - `:connector_gmail` - The unique ID of the shell tool call generated by the model. + - `:connector_googlecalendar` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `:connector_googledrive` - Represents the use of a local environment to perform shell actions. + - `:connector_microsoftteams` - - `class BetaResponseLocalEnvironment` + - `:connector_outlookcalendar` - Represents the use of a local environment to perform shell actions. + - `:connector_outlookemail` - - `type: :local` + - `:connector_sharepoint` - The environment type. Always `local`. + - `defer_loading: bool` - - `:local` + Whether this MCP tool is deferred and discovered via tool search. - - `class BetaResponseContainerReference` + - `headers: Hash[Symbol, String]` - Represents a container created with /v1/containers. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `container_id: String` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `type: :container_reference` + Specify which of the MCP server's tools require approval. - The environment type. Always `container_reference`. + - `class McpToolApprovalFilter` - - `:container_reference` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `status: :in_progress | :completed | :incomplete` + - `always: Always{ 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: bool` - - `: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: Array[String]` - - `type: :shell_call` + List of allowed tool names. - The type of the item. Always `shell_call`. + - `never: Never{ read_only, tool_names}` - - `:shell_call` + A filter object to specify which tools are allowed. - - `agent: Agent{ agent_name}` + - `read_only: bool` - 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: Array[String]` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `McpToolApprovalSetting = :always | :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. - - `class Direct` + - `:always` - - `type: :direct` + - `:never` - - `:direct` + - `server_description: String` - - `class Program` + Optional description of the MCP server, used to provide more context. - - `caller_id: String` + - `server_url: 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: 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: String` + - `class CodeInterpreter` - The ID of the entity that created this tool call. + A tool that runs Python code to help generate a response to a prompt. - - `class BetaResponseFunctionShellToolCallOutput` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - The output of a shell tool call that was emitted. + 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 = String` - The unique ID of the shell call output. Populated when this item is returned via API. + The container ID. - - `call_id: String` + - `class CodeInterpreterToolAuto` - The unique ID of the shell tool call generated by the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `max_output_length: Integer` + - `type: :auto` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Always `auto`. - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `:auto` - An array of shell call output contents + - `file_ids: Array[String]` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + An optional list of uploaded files to make available to your code. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `class Timeout` + The memory limit for the code interpreter container. - Indicates that the shell call exceeded its configured time limit. + - `:"1g"` - - `type: :timeout` + - `:"4g"` - The outcome type. Always `timeout`. + - `:"16g"` - - `:timeout` + - `:"64g"` - - `class Exit` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - Indicates that the shell commands finished and returned an exit code. + Network access policy for the container. - - `exit_code: Integer` + - `class BetaContainerNetworkPolicyDisabled` - Exit code from the shell process. + - `type: :disabled` - - `type: :exit` + Disable outbound network access. Always `disabled`. - The outcome type. Always `exit`. + - `:disabled` - - `:exit` + - `class BetaContainerNetworkPolicyAllowlist` - - `stderr: String` + - `allowed_domains: Array[String]` - The standard error output that was captured. + A list of allowed domains when type is `allowlist`. - - `stdout: String` + - `type: :allowlist` - The standard output that was captured. + Allow outbound network access only to specified domains. Always `allowlist`. - - `created_by: String` + - `:allowlist` - The identifier of the actor that created the item. + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `status: :in_progress | :completed | :incomplete` + Optional domain-scoped secrets for allowlisted domains. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `domain: String` - - `:in_progress` + The domain associated with the secret. - - `:completed` + - `name: String` - - `:incomplete` + The name of the secret to inject for the domain. - - `type: :shell_call_output` + - `value: String` - The type of the shell call output. Always `shell_call_output`. + The secret value to inject for the domain. - - `:shell_call_output` + - `type: :code_interpreter` - - `agent: Agent{ agent_name}` + The type of the code interpreter tool. Always `code_interpreter`. - The agent that produced this item. + - `:code_interpreter` - - `agent_name: String` + - `allowed_callers: Array[:direct | :programmatic]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:direct` - The execution context that produced this tool call. + - `:programmatic` - - `class Direct` + - `class ProgrammaticToolCalling` - - `type: :direct` + - `type: :programmatic_tool_calling` - - `:direct` + The type of the tool. Always `programmatic_tool_calling`. - - `class Program` + - `:programmatic_tool_calling` - - `caller_id: String` + - `class ImageGeneration` - The call ID of the program item that produced this tool call. + A tool that generates images using the GPT image models. - - `type: :program` + - `type: :image_generation` - - `:program` + The type of the image generation tool. Always `image_generation`. - - `created_by: String` + - `:image_generation` - The identifier of the actor that created the item. + - `action: :generate | :edit | :auto` - - `class BetaResponseApplyPatchToolCall` + Whether to generate a new image or edit an existing image. Default: `auto`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `:generate` - - `id: String` + - `:edit` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `:auto` - - `call_id: String` + - `background: :transparent | :opaque | :auto` - The unique ID of the apply patch tool call generated by the model. + 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. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, 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. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `class CreateFile` + - `:transparent` - Instruction describing how to create a file via the apply_patch tool. + - `:opaque` - - `diff: String` + - `:auto` - Diff to apply. + - `input_fidelity: :high | :low` - - `path: 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`. - Path of the file to create. + - `:high` - - `type: :create_file` + - `:low` - Create a new file with the provided diff. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `:create_file` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `class DeleteFile` + - `file_id: String` - Instruction describing how to delete a file via the apply_patch tool. + File ID for the mask image. - - `path: String` + - `image_url: String` - Path of the file to delete. + Base64-encoded mask image. - - `type: :delete_file` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - Delete the specified file. + The image generation model to use. Default: `gpt-image-1`. - - `:delete_file` + - `String = String` - - `class UpdateFile` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - Instruction describing how to update a file via the apply_patch tool. + The image generation model to use. Default: `gpt-image-1`. - - `diff: String` + - `:"gpt-image-1"` - Diff to apply. + - `:"gpt-image-1-mini"` - - `path: String` + - `:"gpt-image-2"` - Path of the file to update. + - `:"gpt-image-2-2026-04-21"` - - `type: :update_file` + - `:"gpt-image-1.5"` - Update an existing file with the provided diff. + - `:"chatgpt-image-latest"` - - `:update_file` + - `moderation: :auto | :low` - - `status: :in_progress | :completed` + Moderation level for the generated image. Default: `auto`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:auto` - - `:in_progress` + - `:low` - - `:completed` + - `output_compression: Integer` - - `type: :apply_patch_call` + Compression level for the output image. Default: 100. - The type of the item. Always `apply_patch_call`. + - `output_format: :png | :webp | :jpeg` - - `:apply_patch_call` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `agent: Agent{ 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: Integer` - - `caller_: Direct{ type} | Program{ 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: :low | :medium | :high | :auto` - - `class Direct` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: :direct` + - `:low` - - `:direct` + - `:medium` - - `class Program` + - `:high` - - `caller_id: String` + - `:auto` - The call ID of the program item that produced this tool call. + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 = String` - - `created_by: String` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - The ID of the entity that created 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`. - - `class BetaResponseApplyPatchToolCallOutput` + - `:"1024x1024"` - The output emitted by an apply patch tool call. + - `:"1024x1536"` - - `id: String` + - `:"1536x1024"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:auto` - - `call_id: String` + - `class LocalShell` - The unique ID of the apply patch tool call generated by the model. + A tool that allows the model to execute shell commands in a local environment. - - `status: :completed | :failed` + - `type: :local_shell` - The status of the apply patch tool call output. One of `completed` or `failed`. + The type of the local shell tool. Always `local_shell`. - - `:completed` + - `:local_shell` - - `:failed` + - `class BetaFunctionShellTool` - - `type: :apply_patch_call_output` + A tool that allows the model to execute shell commands. - The type of the item. Always `apply_patch_call_output`. + - `type: :shell` - - `:apply_patch_call_output` + The type of the shell tool. Always `shell`. - - `agent: Agent{ agent_name}` + - `:shell` - The agent that produced this item. + - `allowed_callers: Array[:direct | :programmatic]` - - `agent_name: String` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `:direct` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:programmatic` - The execution context that produced this tool call. + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `class Direct` + - `class BetaContainerAuto` - - `type: :direct` + - `type: :container_auto` - - `:direct` + Automatically creates a container for this request - - `class Program` + - `:container_auto` - - `caller_id: String` + - `file_ids: Array[String]` - The call ID of the program item that produced this tool call. + An optional list of uploaded files to make available to your code. - - `type: :program` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:program` + The memory limit for the container. - - `created_by: String` + - `:"1g"` - The ID of the entity that created this tool call output. + - `:"4g"` - - `output: String` + - `:"16g"` - Optional textual output returned by the apply patch tool. + - `:"64g"` - - `class McpCall` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - An invocation of a tool on an MCP server. + Network access policy for the container. - - `id: String` + - `class BetaContainerNetworkPolicyDisabled` - The unique ID of the tool call. + - `class BetaContainerNetworkPolicyAllowlist` - - `arguments: String` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - A JSON string of the arguments passed to the tool. + An optional list of skills referenced by id or inline data. - - `name: String` + - `class BetaSkillReference` - The name of the tool that was run. + - `skill_id: String` - - `server_label: String` + The ID of the referenced skill. - The label of the MCP server running the tool. + - `type: :skill_reference` - - `type: :mcp_call` + References a skill created with the /v1/skills endpoint. - The type of the item. Always `mcp_call`. + - `:skill_reference` - - `:mcp_call` + - `version: String` - - `agent: Agent{ agent_name}` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The agent that produced this item. + - `class BetaInlineSkill` - - `agent_name: String` + - `description: String` - The canonical name of the agent that produced this item. + The description of the skill. - - `approval_request_id: String` + - `name: String` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The name of the skill. - - `error: String` + - `source: BetaInlineSkillSource` - The error from the tool call, if any. + Inline skill payload - - `output: String` + - `data: String` - The output from the tool call. + Base64-encoded skill zip bundle. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `media_type: :"application/zip"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The media type of the inline skill payload. Must be `application/zip`. - - `:in_progress` + - `:"application/zip"` - - `:completed` + - `type: :base64` - - `:incomplete` + The type of the inline skill source. Must be `base64`. - - `:calling` + - `:base64` - - `:failed` + - `type: :inline` - - `class McpListTools` + Defines an inline skill for this request. - A list of tools available on an MCP server. + - `:inline` - - `id: String` + - `class BetaLocalEnvironment` - The unique ID of the list. + - `type: :local` - - `server_label: String` + Use a local computer environment. - The label of the MCP server. + - `:local` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `skills: Array[BetaLocalSkill]` - The tools available on the server. + An optional list of skills. - - `input_schema: untyped` + - `description: String` - The JSON schema describing the tool's input. + The description of the skill. - `name: String` - The name of the tool. - - - `annotations: untyped` + The name of the skill. - Additional annotations about the tool. + - `path: String` - - `description: String` + The path to the directory containing the skill. - The description of the tool. + - `class BetaContainerReference` - - `type: :mcp_list_tools` + - `container_id: String` - The type of the item. Always `mcp_list_tools`. + The ID of the referenced container. - - `:mcp_list_tools` + - `type: :container_reference` - - `agent: Agent{ agent_name}` + References a container created with the /v1/containers endpoint - The agent that produced this item. + - `:container_reference` - - `agent_name: String` + - `class BetaCustomTool` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `error: String` + - `name: String` - Error message if the server could not list tools. + The name of the custom tool, used to identify it in tool calls. - - `class McpApprovalRequest` + - `type: :custom` - A request for human approval of a tool invocation. + The type of the custom tool. Always `custom`. - - `id: String` + - `:custom` - The unique ID of the approval request. + - `allowed_callers: Array[:direct | :programmatic]` - - `arguments: String` + The tool invocation context(s). - A JSON string of arguments for the tool. + - `:direct` - - `name: String` + - `:programmatic` - The name of the tool to run. + - `defer_loading: bool` - - `server_label: String` + Whether this tool should be deferred and discovered via tool search. - The label of the MCP server making the request. + - `description: String` - - `type: :mcp_approval_request` + Optional description of the custom tool, used to provide more context. - The type of the item. Always `mcp_approval_request`. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `:mcp_approval_request` + The input format for the custom tool. Default is unconstrained text. - - `agent: Agent{ agent_name}` + - `class Text` - 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`. - - `class McpApprovalResponse` + - `:text` - A response to an MCP approval request. + - `class Grammar` - - `id: String` + A grammar defined by the user. - The unique ID of the approval response + - `definition: String` - - `approval_request_id: String` + The grammar definition. - The ID of the approval request being answered. + - `syntax: :lark | :regex` - - `approve: bool` + The syntax of the grammar definition. One of `lark` or `regex`. - Whether the request was approved. + - `:lark` - - `type: :mcp_approval_response` + - `:regex` - The type of the item. Always `mcp_approval_response`. + - `type: :grammar` - - `:mcp_approval_response` + Grammar format. Always `grammar`. - - `agent: Agent{ agent_name}` + - `:grammar` - The agent that produced this item. + - `class BetaNamespaceTool` - - `agent_name: String` + Groups function/custom tools under a shared namespace. - The canonical name of the agent that produced this item. + - `description: String` - - `reason: String` + A description of the namespace shown to the model. - Optional reason for the decision. + - `name: String` - - `class BetaResponseCustomToolCall` + The namespace name used in tool calls (for example, `crm`). - A call to a custom tool created by the model. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `class BetaResponseCustomToolCallOutputItem` + The function/custom tools available inside this namespace. - The output of a custom tool call from your code, being sent back to the model. + - `class Function` - - `id: String` + - `name: String` - The unique ID of the custom tool call output item. + - `type: :function` - - `status: :in_progress | :completed | :incomplete` + - `:function` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_callers: Array[:direct | :programmatic]` - - `:in_progress` + The tool invocation context(s). - - `:completed` + - `:direct` - - `:incomplete` + - `:programmatic` - - `created_by: String` + - `defer_loading: bool` - The identifier of the actor that created the item. + Whether this function should be deferred and discovered via tool search. - - `parallel_tool_calls: bool` + - `description: String` - Whether to allow the model to run tool calls in parallel. + - `output_schema: Hash[Symbol, untyped]` - - `temperature: Float` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - 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. + - `parameters: untyped` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `strict: bool` - 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. + 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. - - `BetaToolChoiceOptions = :none | :auto | :required` + - `class BetaCustomTool` - Controls which (if any) tool is called by 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) - `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` + - `class BetaToolSearchTool` - - `:auto` + Hosted or BYOT tool search configuration for deferred tools. - - `:required` + - `type: :tool_search` - - `class BetaToolChoiceAllowed` + The type of the tool. Always `tool_search`. - Constrains the tools available to the model to a pre-defined set. + - `:tool_search` - - `mode: :auto | :required` + - `description: 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: :server | :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[Hash[Symbol, untyped]]` + - `parameters: untyped` - 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: + - `class BetaWebSearchPreviewTool` - ```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 | :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` - - `class BetaToolChoiceTypes` + - `: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: Array[:text | :image]` - - `type: :file_search | :web_search_preview | :computer | 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: :low | :medium | :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: UserLocation{ 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` - - `class BetaToolChoiceFunction` + - `city: 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: 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: String` - For function calling, the type is always `function`. + Free text input for the region of the user, e.g. `California`. - - `:function` + - `timezone: String` - - `class BetaToolChoiceMcp` + 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. + - `class BetaApplyPatchTool` - - `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: Array[:direct | :programmatic]` - - `name: String` + The tool invocation context(s). - The name of the tool to call on the server. + - `:direct` - - `class BetaToolChoiceCustom` + - `: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: Agent{ agent_name}` - For custom tool calling, the type is always `custom`. + The agent that produced this item. - - `:custom` + - `agent_name: String` - - `class BetaSpecificProgrammaticToolCallingParam` + The canonical name of the agent that produced this item. - - `type: :programmatic_tool_calling` + - `created_by: String` - The tool to call. Always `programmatic_tool_calling`. + The identifier of the actor that created the item. - - `:programmatic_tool_calling` + - `class AdditionalTools` - - `class BetaToolChoiceApplyPatch` + - `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 | :user | :assistant | 5 more` - The tool to call. Always `apply_patch`. + The role that provided the additional tools. - - `:apply_patch` + - `:unknown` - - `class BetaToolChoiceShell` + - `: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[BetaTool]` + - `: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[BetaTool]` - - **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. - `class BetaFunctionTool` @@ -24634,1053 +35271,825 @@ Create a model response - `class BetaToolSearchTool` - Hosted or BYOT tool search configuration for deferred tools. + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The type of the item. Always `additional_tools`. + + - `:additional_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: String` + + The unique ID of the compaction item. - - `class BetaWebSearchPreviewTool` + - `encrypted_content: String` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The encrypted content that was produced by compaction. - - `class BetaApplyPatchTool` + - `type: :compaction` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the item. Always `compaction`. - - `top_p: Float` + - `:compaction` - 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: Agent{ agent_name}` - We generally recommend altering this or `temperature` but not both. + The agent that produced this item. - - `background: bool` + - `agent_name: String` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The canonical name of the agent that produced this item. - - `completed_at: Float` + - `created_by: String` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The identifier of the actor that created the item. - - `conversation: Conversation{ id}` + - `class ImageGenerationCall` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + An image generation request made by the model. - `id: String` - The unique ID of the conversation that this response was associated with. + The unique ID of the image generation call. - - `max_output_tokens: Integer` + - `result: 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 generated image encoded in base64. - - `max_tool_calls: Integer` + - `status: :in_progress | :completed | :generating | :failed` - 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 status of the image generation call. - - `moderation: Moderation{ input, output}` + - `:in_progress` - Moderation results for the response input and output, if moderated completions were requested. + - `:completed` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `:generating` - Moderation for the response input. + - `:failed` - - `class ModerationResult` + - `type: :image_generation_call` - A moderation result produced for the response input or output. + The type of the image generation call. Always `image_generation_call`. - - `categories: Hash[Symbol, bool]` + - `:image_generation_call` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `agent: Agent{ agent_name}` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The agent that produced this item. - Which modalities of input are reflected by the score for each category. + - `agent_name: String` - - `:text` + The canonical name of the agent that produced this item. - - `:image` + - `class BetaResponseCodeInterpreterToolCall` - - `category_scores: Hash[Symbol, Float]` + A tool call to run code. - A dictionary of moderation categories to scores. + - `id: String` - - `flagged: bool` + The unique ID of the code interpreter tool call. - A boolean indicating whether the content was flagged by any category. + - `code: String` - - `model: String` + The code to run, or null if not available. - The moderation model that produced this result. + - `container_id: String` - - `type: :moderation_result` + The ID of the container used to run the code. - The object type, which was always `moderation_result` for successful moderation results. + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `:moderation_result` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `class Error` + - `class Logs` - An error produced while attempting moderation for the response input or output. + The logs output from the code interpreter. - - `code: String` + - `logs: String` - The error code. + The logs output from the code interpreter. - - `message: String` + - `type: :logs` - The error message. + The type of the output. Always `logs`. - - `type: :error` + - `:logs` - The object type, which was always `error` for moderation failures. + - `class Image` - - `:error` + The image output from the code interpreter. - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `type: :image` - Moderation for the response output. + The type of the output. Always `image`. - - `class ModerationResult` + - `:image` - A moderation result produced for the response input or output. + - `url: String` - - `categories: Hash[Symbol, bool]` + The URL of the image output from the code interpreter. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Which modalities of input are reflected by the score for each category. + - `:in_progress` - - `:text` + - `:completed` - - `:image` + - `:incomplete` - - `category_scores: Hash[Symbol, Float]` + - `:interpreting` - A dictionary of moderation categories to scores. + - `:failed` - - `flagged: bool` + - `type: :code_interpreter_call` - A boolean indicating whether the content was flagged by any category. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `model: String` + - `:code_interpreter_call` - The moderation model that produced this result. + - `agent: Agent{ 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. - - `class Error` + - `class LocalShellCall` - An error produced while attempting moderation for the response input or output. + A tool call to run a command on the local shell. - - `code: String` + - `id: String` - The error code. + The unique ID of the local shell call. - - `message: String` + - `action: Action{ command, env, type, 3 more}` - The error message. + Execute a shell command on the server. - - `type: :error` + - `command: Array[String]` - The object type, which was always `error` for moderation failures. + The command to run. - - `:error` + - `env: Hash[Symbol, String]` - - `previous_response_id: String` + Environment variables to set for the command. - 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: :exec` - - `prompt: BetaResponsePrompt` + The type of the local shell action. Always `exec`. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `:exec` - - `id: String` + - `timeout_ms: Integer` - The unique identifier of the prompt template to use. + Optional timeout in milliseconds for the command. - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `user: 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. + Optional user to run the command as. - - `String = String` + - `working_directory: String` - - `class BetaResponseInputText` + Optional working directory to run the command in. - A text input to the model. + - `call_id: String` - - `class BetaResponseInputImage` + The unique ID of the local shell tool call generated by the model. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `status: :in_progress | :completed | :incomplete` - - `class BetaResponseInputFile` + The status of the local shell call. - A file input to the model. + - `:in_progress` - - `version: String` + - `:completed` - Optional version of the prompt template. + - `:incomplete` - - `prompt_cache_key: String` + - `type: :local_shell_call` - 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 type of the local shell call. Always `local_shell_call`. - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `:local_shell_call` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `agent: Agent{ agent_name}` - - `mode: :implicit | :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` + - `class LocalShellCallOutput` - - `ttl: :"30m"` + The output of a local shell tool call. - The minimum lifetime applied to each cache breakpoint. + - `id: String` - - `:"30m"` + The unique ID of the local shell tool call generated by the model. - - `prompt_cache_retention: :in_memory | :"24h"` + - `output: String` - Deprecated. Use `prompt_cache_options.ttl` instead. + A JSON string of the output of the local shell tool call. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](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: :local_shell_call_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 local shell tool call output. Always `local_shell_call_output`. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `:local_shell_call_output` - - `:in_memory` + - `agent: Agent{ agent_name}` - - `:"24h"` + The agent that produced this item. - - `reasoning: Reasoning{ 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). + - `status: :in_progress | :completed | :incomplete` - - `context: :auto | :current_turn | :all_turns` + The status of the item. One of `in_progress`, `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. + - `:in_progress` - - `:auto` + - `:completed` - - `:current_turn` + - `:incomplete` - - `:all_turns` + - `class BetaResponseFunctionShellToolCall` - - `effort: :none | :minimal | :low | 4 more` + A tool call that executes one or more shell commands in a managed environment. - 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 shell tool call. Populated when this item is returned via API. - - `:minimal` + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:low` + The shell commands and limits that describe how to run the tool call. - - `:medium` + - `commands: Array[String]` - - `:high` + - `max_output_length: Integer` - - `:xhigh` + Optional maximum number of characters to return from each command. - - `:max` + - `timeout_ms: Integer` - - `generate_summary: :auto | :concise | :detailed` + Optional timeout in milliseconds for the commands. - **Deprecated:** use `summary` instead. + - `call_id: String` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The unique ID of the shell tool call generated by the model. - - `:auto` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:concise` + Represents the use of a local environment to perform shell actions. - - `:detailed` + - `class BetaResponseLocalEnvironment` - - `mode: String | :standard | :pro` + Represents the use of a local environment to perform shell actions. - Controls the reasoning execution mode for the request. + - `type: :local` - When returned on a response, this is the effective execution mode. + The environment type. Always `local`. - - `String = String` + - `:local` - - `Mode = :standard | :pro` + - `class BetaResponseContainerReference` - Controls the reasoning execution mode for the request. + Represents a container created with /v1/containers. - When returned on a response, this is the effective execution mode. + - `container_id: String` - - `:standard` + - `type: :container_reference` - - `:pro` + The environment type. Always `container_reference`. - - `summary: :auto | :concise | :detailed` + - `:container_reference` - 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: :in_progress | :completed | :incomplete` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:auto` + - `:in_progress` - - `:concise` + - `:completed` - - `:detailed` + - `:incomplete` - - `safety_identifier: String` + - `type: :shell_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). + The type of the item. Always `shell_call`. - - `service_tier: :auto | :default | :flex | 2 more` + - `:shell_call` - Specifies the processing type used for serving the request. + - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - `:flex` + The execution context that produced this tool call. - - `:scale` + - `class Direct` - - `:priority` + - `type: :direct` - - `status: BetaResponseStatus` + - `:direct` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `class Program` - - `:completed` + - `caller_id: String` - - `:failed` + The call ID of the program item that produced this tool call. - - `:in_progress` + - `type: :program` - - `:cancelled` + - `:program` - - `:queued` + - `created_by: String` - - `:incomplete` + The ID of the entity that created this tool call. - - `text: BetaResponseTextConfig` + - `class BetaResponseFunctionShellToolCallOutput` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The output of a shell tool call that was emitted. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `id: String` - - `format_: BetaResponseFormatTextConfig` + The unique ID of the shell call output. Populated when this item is returned via API. - An object specifying the format that the model must output. + - `call_id: String` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the shell tool call generated by the model. - The default format is `{ "type": "text" }` with no additional options. + - `max_output_length: Integer` - **Not recommended for gpt-4o and newer models:** + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw 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. + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `class Text` + An array of shell call output contents - Default response format. Used to generate text responses. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `type: :text` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The type of response format being defined. Always `text`. + - `class Timeout` - - `:text` + Indicates that the shell call exceeded its configured time limit. - - `class BetaResponseFormatTextJSONSchemaConfig` + - `type: :timeout` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The outcome type. Always `timeout`. - - `name: String` + - `:timeout` - 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. + - `class Exit` - - `schema: Hash[Symbol, untyped]` + Indicates that the shell commands finished and returned an exit code. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `exit_code: Integer` - - `type: :json_schema` + Exit code from the shell process. - The type of response format being defined. Always `json_schema`. + - `type: :exit` - - `:json_schema` + The outcome type. Always `exit`. - - `description: String` + - `:exit` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `stderr: String` - - `strict: bool` + The standard error output that was captured. - 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). + - `stdout: String` - - `class JSONObject` + The standard output that was captured. - 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. + - `created_by: String` - - `type: :json_object` + The identifier of the actor that created the item. - The type of response format being defined. Always `json_object`. + - `status: :in_progress | :completed | :incomplete` - - `:json_object` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `verbosity: :low | :medium | :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` + - `type: :shell_call_output` - - `:high` + The type of the shell call output. Always `shell_call_output`. - - `top_logprobs: Integer` + - `:shell_call_output` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `agent: Agent{ agent_name}` - - `truncation: :auto | :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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:disabled` + The execution context that produced this tool call. - - `usage: BetaResponseUsage` + - `class Direct` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `type: :direct` - - `input_tokens: Integer` + - `:direct` - The number of input tokens. + - `class Program` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `caller_id: String` - A detailed breakdown of the input tokens. + The call ID of the program item that produced this tool call. - - `cache_write_tokens: Integer` + - `type: :program` - The number of input tokens that were written to the cache. + - `:program` - - `cached_tokens: Integer` + - `created_by: String` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The identifier of the actor that created the item. - - `output_tokens: Integer` + - `class BetaResponseApplyPatchToolCall` - The number of output tokens. + A tool call that applies file diffs by creating, deleting, or updating files. - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `id: String` - A detailed breakdown of the output tokens. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `reasoning_tokens: Integer` + - `call_id: String` - The number of reasoning tokens. + The unique ID of the apply patch tool call generated by the model. - - `total_tokens: Integer` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The total number of tokens used. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `user: String` + - `class CreateFile` - 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). + Instruction describing how to create a file via the apply_patch tool. -### Example + - `diff: String` -```ruby -require "openai" + Diff to apply. -openai = OpenAI::Client.new(api_key: "My API Key") + - `path: String` -beta_response = openai.beta.responses.create + Path of the file to create. -puts(beta_response) -``` + - `type: :create_file` -#### Response + Create a new file with the provided diff. -```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" -} -``` + - `:create_file` -## Get a model response + - `class DeleteFile` -`beta.responses.retrieve(response_id, **kwargs) -> BetaResponse` + Instruction describing how to delete a file via the apply_patch tool. -**get** `/responses/{response_id}?beta=true` + - `path: String` -Get a model response + Path of the file to delete. -### Parameters + - `type: :delete_file` -- `response_id: String` + Delete the specified file. -- `include: Array[BetaResponseIncludable]` + - `:delete_file` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `class UpdateFile` - - `:"file_search_call.results"` + Instruction describing how to update a file via the apply_patch tool. - - `:"web_search_call.results"` + - `diff: String` - - `:"web_search_call.action.sources"` + Diff to apply. - - `:"message.input_image.image_url"` + - `path: String` - - `:"computer_call_output.output.image_url"` + Path of the file to update. - - `:"code_interpreter_call.outputs"` + - `type: :update_file` - - `:"reasoning.encrypted_content"` + Update an existing file with the provided diff. - - `:"message.output_text.logprobs"` + - `:update_file` -- `include_obfuscation: bool` + - `status: :in_progress | :completed` - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events - to normalize payload sizes as a mitigation to certain side-channel - attacks. These obfuscation fields are included by default, but add a - small amount of overhead to the data stream. You can set - `include_obfuscation` to false to optimize for bandwidth if you trust - the network links between your application and the OpenAI API. + The status of the apply patch tool call. One of `in_progress` or `completed`. -- `starting_after: Integer` + - `:in_progress` - The sequence number of the event after which to start streaming. + - `:completed` -- `stream: bool` + - `type: :apply_patch_call` - 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. + The type of the item. Always `apply_patch_call`. -- `betas: Array[:"responses_multi_agent=v1"]` + - `:apply_patch_call` - - `:"responses_multi_agent=v1"` + - `agent: Agent{ agent_name}` -### Returns + The agent that produced this item. -- `class BetaResponse` + - `agent_name: String` - - `id: String` + The canonical name of the agent that produced this item. - Unique identifier for this Response. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `created_at: Float` + The execution context that produced this tool call. - Unix timestamp (in seconds) of when this Response was created. + - `class Direct` - - `error: BetaResponseError` + - `type: :direct` - An error object returned when the model fails to generate a Response. + - `:direct` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `class Program` - 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` + - `:program` - - `:bio_policy` + - `created_by: String` - - `:vector_store_timeout` + The ID of the entity that created this tool call. - - `:invalid_image` + - `class BetaResponseApplyPatchToolCallOutput` - - `:invalid_image_format` + The output emitted by an apply patch tool call. - - `:invalid_base64_image` + - `id: String` - - `:invalid_image_url` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `:image_too_large` + - `call_id: String` - - `:image_too_small` + The unique ID of the apply patch tool call generated by the model. - - `:image_parse_error` + - `status: :completed | :failed` - - `:image_content_policy_violation` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `:invalid_image_mode` + - `:completed` - - `:image_file_too_large` + - `:failed` - - `:unsupported_image_media_type` + - `type: :apply_patch_call_output` - - `:empty_image_file` + The type of the item. Always `apply_patch_call_output`. - - `:failed_to_download_image` + - `:apply_patch_call_output` - - `:image_file_not_found` + - `agent: Agent{ agent_name}` - - `message: String` + The agent that produced this item. - A human-readable description of the error. + - `agent_name: String` - - `incomplete_details: IncompleteDetails{ reason}` + The canonical name of the agent that produced this item. - Details about why the response is incomplete. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `reason: :max_output_tokens | :content_filter` + The execution context that produced this tool call. - The reason why the response is incomplete. + - `class Direct` - - `:max_output_tokens` + - `type: :direct` - - `:content_filter` + - `:direct` - - `instructions: String | Array[BetaResponseInputItem]` + - `class Program` - A system (or developer) message inserted into the model's context. + - `caller_id: String` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + The call ID of the program item that produced this tool call. - - `String = String` + - `type: :program` - A text input to the model, equivalent to a text input with the - `developer` role. + - `:program` - - `InputItemList = Array[BetaResponseInputItem]` + - `created_by: String` - A list of one or many input items to the model, containing - different content types. + The ID of the entity that created this tool call output. - - `class BetaEasyInputMessage` + - `output: 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. + Optional textual output returned by the apply patch tool. - - `content: String | BetaResponseInputMessageContentList` + - `class McpCall` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + An invocation of a tool on an MCP server. - - `String = String` + - `id: String` - A text input to the model. + The unique ID of the tool call. - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `arguments: String` - A list of one or many input items to the model, containing different content - types. + A JSON string of the arguments passed to the tool. - - `class BetaResponseInputText` + - `name: String` - A text input to the model. + The name of the tool that was run. - - `text: String` + - `server_label: String` - The text input to the model. + The label of the MCP server running the tool. - - `type: :input_text` + - `type: :mcp_call` - The type of the input item. Always `input_text`. + The type of the item. Always `mcp_call`. - - `:input_text` + - `:mcp_call` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `agent: Agent{ 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` + - `approval_request_id: String` - - `class BetaResponseInputImage` + 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 image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `error: String` - - `detail: :low | :high | :auto | :original` + The error from the tool call, if any. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `output: String` - - `:low` + The output from the tool call. - - `:high` + - `status: :in_progress | :completed | :incomplete | 2 more` - - `:auto` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `:original` + - `:in_progress` - - `type: :input_image` + - `:completed` - The type of the input item. Always `input_image`. + - `:incomplete` - - `:input_image` + - `:calling` - - `file_id: String` + - `:failed` - The ID of the file to be sent to the model. + - `class McpListTools` - - `image_url: String` + A list of tools available on an MCP server. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The unique ID of the list. - Marks the exact end of a reusable 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. - The breakpoint mode. Always `explicit`. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `:explicit` + The tools available on the server. - - `class BetaResponseInputFile` + - `input_schema: untyped` - A file input to the model. + The JSON schema describing the tool's input. - - `type: :input_file` + - `name: String` - The type of the input item. Always `input_file`. + The name of the tool. - - `:input_file` + - `annotations: untyped` - - `detail: :auto | :low | :high` + Additional annotations about 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`. + - `description: String` - - `:auto` + The description of the tool. - - `:low` + - `type: :mcp_list_tools` - - `:high` + The type of the item. Always `mcp_list_tools`. - - `file_data: String` + - `:mcp_list_tools` - The content of the file to be sent to the model. + - `agent: Agent{ agent_name}` - - `file_id: String` + The agent that produced this item. - The ID of the file to be sent to the model. + - `agent_name: String` - - `file_url: String` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. + - `error: String` - - `filename: String` + Error message if the server could not list tools. - The name of the file to be sent to the model. + - `class McpApprovalRequest` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A request for human approval of a tool invocation. - Marks the exact end of a reusable 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 approval request. - The breakpoint mode. Always `explicit`. + - `arguments: String` - - `:explicit` + A JSON string of arguments for the tool. - - `role: :user | :assistant | :system | :developer` + - `name: String` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The name of the tool to run. - - `:user` + - `server_label: String` - - `:assistant` + The label of the MCP server making the request. - - `:system` + - `type: :mcp_approval_request` - - `:developer` + The type of the item. Always `mcp_approval_request`. - - `phase: :commentary` + - `: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. + - `agent: Agent{ agent_name}` - - `:commentary` + The agent that produced this item. - - `type: :message` + - `agent_name: String` + + The canonical name of the agent that produced this item. - The type of the message input. Always `message`. + - `class McpApprovalResponse` - - `:message` + A response to an MCP approval request. - - `class Message` + - `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 unique ID of the approval response - - `content: BetaResponseInputMessageContentList` + - `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. - - `role: :user | :system | :developer` + - `approve: bool` - The role of the message input. One of `user`, `system`, or `developer`. + Whether the request was approved. - - `:user` + - `type: :mcp_approval_response` - - `:system` + The type of the item. Always `mcp_approval_response`. - - `:developer` + - `:mcp_approval_response` - `agent: Agent{ agent_name}` @@ -25690,343 +36099,331 @@ Get a model response The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` + - `reason: String` - - `type: :message` + Optional reason for the decision. - The type of the message input. Always set to `message`. + - `class BetaResponseCustomToolCall` - - `:message` + A call to a custom tool created by the model. - - `class BetaResponseOutputMessage` + - `call_id: String` - An output message from the model. + An identifier used to map this custom tool call to a tool call output. - - `id: String` + - `input: String` - The unique ID of the output message. + The input for the custom tool call generated by the model. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `name: String` - The content of the output message. + The name of the custom tool being called. - - `class BetaResponseOutputText` + - `type: :custom_tool_call` - A text output from the model. + The type of the custom tool call. Always `custom_tool_call`. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `:custom_tool_call` - The annotations of the text output. + - `id: String` - - `class FileCitation` + The unique ID of the custom tool call in the OpenAI platform. - A citation to a file. + - `agent: Agent{ agent_name}` - - `file_id: String` + The agent that produced this item. - The ID of the file. + - `agent_name: String` - - `filename: String` + The canonical name of the agent that produced this item. - The filename of the file cited. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `index: Integer` + The execution context that produced this tool call. - The index of the file in the list of files. + - `class Direct` - - `type: :file_citation` + - `type: :direct` - The type of the file citation. Always `file_citation`. + - `:direct` - - `:file_citation` + - `class Program` - - `class URLCitation` + - `caller_id: String` - A citation for a web resource used to generate a model response. + The call ID of the program item that produced this tool call. - - `end_index: Integer` + - `type: :program` - The index of the last character of the URL citation in the message. + - `:program` - - `start_index: Integer` + - `namespace: String` - The index of the first character of the URL citation in the message. + The namespace of the custom tool being called. - - `title: String` + - `class BetaResponseCustomToolCallOutputItem` - The title of the web resource. + The output of a custom tool call from your code, being sent back to the model. - - `type: :url_citation` + - `id: String` - The type of the URL citation. Always `url_citation`. + The unique ID of the custom tool call output item. - - `:url_citation` + - `status: :in_progress | :completed | :incomplete` - - `url: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The URL of the web resource. + - `:in_progress` - - `class ContainerFileCitation` + - `:completed` - A citation for a container file used to generate a model response. + - `:incomplete` - - `container_id: String` + - `created_by: String` - The ID of the container file. + The identifier of the actor that created the item. - - `end_index: Integer` + - `usage: BetaResponseUsage` - The index of the last character of the container file citation in the message. + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - `file_id: String` + - `input_tokens: Integer` - The ID of the file. + The number of input tokens. - - `filename: String` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - The filename of the container file cited. + A detailed breakdown of the input tokens. - - `start_index: Integer` + - `cache_write_tokens: Integer` - The index of the first character of the container file citation in the message. + The number of input tokens that were written to the cache. - - `type: :container_file_citation` + - `cached_tokens: Integer` - The type of the container file citation. Always `container_file_citation`. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `:container_file_citation` + - `output_tokens: Integer` - - `class FilePath` + The number of output tokens. - A path to a file. + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - - `file_id: String` + A detailed breakdown of the output tokens. - The ID of the file. + - `reasoning_tokens: Integer` - - `index: Integer` + The number of reasoning tokens. - The index of the file in the list of files. + - `total_tokens: Integer` - - `type: :file_path` + The total number of tokens used. - The type of the file path. Always `file_path`. +### Beta Computer Action - - `:file_path` +- `BetaComputerAction = Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - `text: String` + A click action. - The text output from the model. + - `class Click` - - `type: :output_text` + A click action. - The type of the output text. Always `output_text`. + - `button: :left | :right | :wheel | 2 more` - - `:output_text` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:left` - - `token: String` + - `:right` - - `bytes: Array[Integer]` + - `:wheel` - - `logprob: Float` + - `:back` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `:forward` - - `token: String` + - `type: :click` - - `bytes: Array[Integer]` + Specifies the event type. For a click action, this property is always `click`. - - `logprob: Float` + - `:click` - - `class BetaResponseOutputRefusal` + - `x: Integer` - A refusal from the model. + The x-coordinate where the click occurred. - - `refusal: String` + - `y_: Integer` - The refusal explanation from the model. + The y-coordinate where the click occurred. - - `type: :refusal` + - `keys: Array[String]` - The type of the refusal. Always `refusal`. + The keys being held while clicking. - - `:refusal` + - `class DoubleClick` - - `role: :assistant` + A double click action. - The role of the output message. Always `assistant`. + - `keys: Array[String]` - - `:assistant` + The keys being held while double-clicking. - - `status: :in_progress | :completed | :incomplete` + - `type: :double_click` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `:in_progress` + - `:double_click` - - `:completed` + - `x: Integer` - - `:incomplete` + The x-coordinate where the double click occurred. - - `type: :message` + - `y_: Integer` - The type of the output message. Always `message`. + The y-coordinate where the double click occurred. - - `:message` + - `class Drag` - - `agent: Agent{ agent_name}` + A drag action. - The agent that produced this item. + - `path: Array[Path{ x, y_}]` - - `agent_name: String` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The canonical name of the agent that produced this item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `phase: :commentary` + - `x: Integer` - 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 x-coordinate. - - `:commentary` + - `y_: Integer` - - `class BetaResponseFileSearchToolCall` + The y-coordinate. - 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: :drag` - - `id: String` + Specifies the event type. For a drag action, this property is always set to `drag`. - The unique ID of the file search tool call. + - `:drag` - - `queries: Array[String]` + - `keys: Array[String]` - The queries used to search for files. + The keys being held while dragging the mouse. - - `status: :in_progress | :searching | :completed | 2 more` + - `class Keypress` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + A collection of keypresses the model would like to perform. - - `:in_progress` + - `keys: Array[String]` - - `:searching` + 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`. - - `:failed` + - `:keypress` - - `type: :file_search_call` + - `class Move` - The type of the file search tool call. Always `file_search_call`. + A mouse move action. - - `:file_search_call` + - `type: :move` - - `agent: Agent{ agent_name}` + Specifies the event type. For a move action, this property is always set to `move`. - The agent that produced this item. + - `:move` - - `agent_name: String` + - `x: Integer` - The canonical name of the agent that produced this item. + The x-coordinate to move to. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `y_: Integer` - The results of the file search tool call. + The y-coordinate to move to. - - `attributes: Hash[Symbol, String | Float | bool]` + - `keys: Array[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 keys being held while moving the mouse. - - `String = String` + - `class Screenshot` - - `Float = Float` + A screenshot action. - - `UnionMember2 = bool` + - `type: :screenshot` - - `file_id: String` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The unique ID of the file. + - `:screenshot` - - `filename: String` + - `class Scroll` - The name of the file. + A scroll action. - - `score: Float` + - `scroll_x: Integer` - The relevance score of the file - a value between 0 and 1. + The horizontal scroll distance. - - `text: String` + - `scroll_y: Integer` - The text that was retrieved from the file. + The vertical scroll distance. - - `class BetaResponseComputerToolCall` + - `type: :scroll` - 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. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `id: String` + - `:scroll` - The unique ID of the computer call. + - `x: Integer` - - `call_id: String` + The x-coordinate where the scroll occurred. - An identifier used when responding to the tool call with output. + - `y_: Integer` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + The y-coordinate where the scroll occurred. - The pending safety checks for the computer call. + - `keys: Array[String]` - - `id: String` + The keys being held while scrolling. - The ID of the pending safety check. + - `class Type` - - `code: String` + An action to type in text. - The type of the pending safety check. + - `text: String` - - `message: String` + The text to type. - Details about the pending safety check. + - `type: :type` - - `status: :in_progress | :completed | :incomplete` + Specifies the event type. For a type action, this property is always set to `type`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:type` - - `:in_progress` + - `class Wait` - - `:completed` + A wait action. - - `:incomplete` + - `type: :wait` - - `type: :computer_call` + Specifies the event type. For a wait action, this property is always set to `wait`. - The type of the computer call. Always `computer_call`. + - `:wait` - - `:computer_call` +### Beta Computer Action List - - `action: BetaComputerAction` +- `BetaComputerActionList = Array[BetaComputerAction]` - A click action. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `class Click` @@ -26219,321 +36616,337 @@ Get a model response - `:wait` - - `actions: BetaComputerActionList` +### Beta Computer Tool - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. +- `class BetaComputerTool` - - `class Click` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A click action. + - `type: :computer` - - `class DoubleClick` + The type of the computer tool. Always `computer`. - A double click action. + - `:computer` - - `class Drag` +### Beta Computer Use Preview Tool - A drag action. +- `class BetaComputerUsePreviewTool` - - `class Keypress` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A collection of keypresses the model would like to perform. + - `display_height: Integer` - - `class Move` + The height of the computer display. - A mouse move action. + - `display_width: Integer` - - `class Screenshot` + The width of the computer display. - A screenshot action. + - `environment: :windows | :mac | :linux | 2 more` - - `class Scroll` + The type of computer environment to control. - A scroll action. + - `:windows` - - `class Type` + - `:mac` - An action to type in text. + - `:linux` - - `class Wait` + - `:ubuntu` - A wait action. + - `:browser` - - `agent: Agent{ 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. +### Beta Container Auto - - `class ComputerCallOutput` +- `class BetaContainerAuto` - The output of a computer tool call. + - `type: :container_auto` - - `call_id: String` + Automatically creates a container for this request - The ID of the computer tool call that produced the output. + - `:container_auto` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `file_ids: Array[String]` - A computer screenshot image used with the computer use tool. + An optional list of uploaded files to make available to your code. - - `type: :computer_screenshot` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The memory limit for the container. - - `:computer_screenshot` + - `:"1g"` - - `file_id: String` + - `:"4g"` - The identifier of an uploaded file that contains the screenshot. + - `:"16g"` - - `image_url: String` + - `:"64g"` - The URL of the screenshot image. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `type: :computer_call_output` + Network access policy for the container. - The type of the computer tool call output. Always `computer_call_output`. + - `class BetaContainerNetworkPolicyDisabled` - - `:computer_call_output` + - `type: :disabled` - - `id: String` + Disable outbound network access. Always `disabled`. - The ID of the computer tool call output. + - `:disabled` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `class BetaContainerNetworkPolicyAllowlist` - The safety checks reported by the API that have been acknowledged by the developer. + - `allowed_domains: Array[String]` - - `id: String` + A list of allowed domains when type is `allowlist`. - The ID of the pending safety check. + - `type: :allowlist` - - `code: String` + Allow outbound network access only to specified domains. Always `allowlist`. - The type of the pending safety check. + - `:allowlist` - - `message: String` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - Details about the pending safety check. + Optional domain-scoped secrets for allowlisted domains. - - `agent: Agent{ agent_name}` + - `domain: String` - The agent that produced this item. + The domain associated with the secret. - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the secret to inject for the domain. - - `status: :in_progress | :completed | :incomplete` + - `value: String` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The secret value to inject for the domain. - - `:in_progress` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `:completed` + An optional list of skills referenced by id or inline data. - - `:incomplete` + - `class BetaSkillReference` - - `class BetaResponseFunctionWebSearch` + - `skill_id: 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 ID of the referenced skill. - - `id: String` + - `type: :skill_reference` - The unique ID of the web search tool call. + References a skill created with the /v1/skills endpoint. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `:skill_reference` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `version: String` - - `class Search` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Action type "search" - Performs a web search query. + - `class BetaInlineSkill` - - `type: :search` + - `description: String` - The action type. + The description of the skill. - - `:search` + - `name: String` - - `queries: Array[String]` + The name of the skill. - The search queries. + - `source: BetaInlineSkillSource` - - `query: String` + Inline skill payload - The search query. + - `data: String` - - `sources: Array[Source{ type, url}]` + Base64-encoded skill zip bundle. - The sources used in the search. + - `media_type: :"application/zip"` - - `type: :url` + The media type of the inline skill payload. Must be `application/zip`. - The type of source. Always `url`. + - `:"application/zip"` - - `:url` + - `type: :base64` - - `url: String` + The type of the inline skill source. Must be `base64`. - The URL of the source. + - `:base64` - - `class OpenPage` + - `type: :inline` - Action type "open_page" - Opens a specific URL from search results. + Defines an inline skill for this request. - - `type: :open_page` + - `:inline` - The action type. +### Beta Container Network Policy Allowlist - - `:open_page` +- `class BetaContainerNetworkPolicyAllowlist` - - `url: String` + - `allowed_domains: Array[String]` - The URL opened by the model. + A list of allowed domains when type is `allowlist`. - - `class FindInPage` + - `type: :allowlist` - Action type "find_in_page": Searches for a pattern within a loaded page. + Allow outbound network access only to specified domains. Always `allowlist`. - - `pattern: String` + - `:allowlist` - The pattern or text to search for within the page. + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `type: :find_in_page` + Optional domain-scoped secrets for allowlisted domains. - The action type. + - `domain: String` - - `:find_in_page` + The domain associated with the secret. - - `url: String` + - `name: String` - The URL of the page searched for the pattern. + The name of the secret to inject for the domain. - - `status: :in_progress | :searching | :completed | :failed` + - `value: String` - The status of the web search tool call. + The secret value to inject for the domain. - - `:in_progress` +### Beta Container Network Policy Disabled - - `:searching` +- `class BetaContainerNetworkPolicyDisabled` - - `:completed` + - `type: :disabled` - - `:failed` + Disable outbound network access. Always `disabled`. - - `type: :web_search_call` + - `:disabled` - The type of the web search tool call. Always `web_search_call`. +### Beta Container Network Policy Domain Secret - - `:web_search_call` +- `class BetaContainerNetworkPolicyDomainSecret` - - `agent: Agent{ agent_name}` + - `domain: String` - The agent that produced this item. + The domain associated with the secret. - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the secret to inject for the domain. - - `class BetaResponseFunctionToolCall` + - `value: String` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The secret value to inject for the domain. - - `arguments: String` +### Beta Container Reference - A JSON string of the arguments to pass to the function. +- `class BetaContainerReference` - - `call_id: String` + - `container_id: String` - The unique ID of the function tool call generated by the model. + The ID of the referenced container. + + - `type: :container_reference` + + References a container created with the /v1/containers endpoint + + - `:container_reference` + +### Beta Custom Tool + +- `class BetaCustomTool` + + 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 function to run. + The name of the custom tool, used to identify it in tool calls. - - `type: :function_call` + - `type: :custom` - The type of the function tool call. Always `function_call`. + The type of the custom tool. Always `custom`. - - `:function_call` + - `:custom` - - `id: String` + - `allowed_callers: Array[:direct | :programmatic]` - The unique ID of the function tool call. + The tool invocation context(s). - - `agent: Agent{ agent_name}` + - `:direct` - The agent that produced this item. + - `:programmatic` - - `agent_name: String` + - `defer_loading: bool` - The canonical name of the agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `description: String` - The execution context that produced this tool call. + Optional description of the custom tool, used to provide more context. - - `class Direct` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `type: :direct` + The input format for the custom tool. Default is unconstrained text. - - `:direct` + - `class Text` - - `class Program` + 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` - - `:program` + - `class Grammar` - - `namespace: String` + A grammar defined by the user. - The namespace of the function to run. + - `definition: String` - - `status: :in_progress | :completed | :incomplete` + The grammar definition. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `syntax: :lark | :regex` - - `:in_progress` + The syntax of the grammar definition. One of `lark` or `regex`. - - `:completed` + - `:lark` - - `:incomplete` + - `:regex` - - `class FunctionCallOutput` + - `type: :grammar` - The output of a function tool call. + Grammar format. Always `grammar`. - - `call_id: String` + - `:grammar` - The unique ID of the function tool call generated by the model. +### Beta Easy Input Message - - `output: String | BetaResponseFunctionCallOutputItemList` +- `class BetaEasyInputMessage` - Text, image, or file output of the function 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. + + - `content: String | BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - `String = String` - A JSON string of the output of the function tool call. + A text input to the model. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `BetaResponseInputMessageContentList = Array[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. - - `class BetaResponseInputTextContent` + - `class BetaResponseInputText` A text input to the model. @@ -26557,15 +36970,9 @@ Get a model response - `:explicit` - - `class BetaResponseInputImageContent` - - 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`. + - `class BetaResponseInputImage` - - `:input_image` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: :low | :high | :auto | :original` @@ -26579,6 +36986,12 @@ Get a model response - `:original` + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + - `file_id: String` The ID of the file to be sent to the model. @@ -26597,7 +37010,7 @@ Get a model response - `:explicit` - - `class BetaResponseInputFileContent` + - `class BetaResponseInputFile` A file input to the model. @@ -26619,7 +37032,7 @@ Get a model response - `file_data: 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: String` @@ -26643,664 +37056,598 @@ Get a model response - `:explicit` - - `type: :function_call_output` - - The type of the function tool call output. Always `function_call_output`. - - - `:function_call_output` - - - `id: String` - - The unique ID of the function tool call output. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - The caller type. Always `program`. - - - `:program` - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class AgentMessage` - - A message routed between agents. - - - `author: String` - - The sending agent identity. - - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - Plaintext, image, or encrypted content sent between agents. - - - `class BetaResponseInputTextContent` - - A text input to the model. - - - `class BetaResponseInputImageContent` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `class EncryptedContent` + - `role: :user | :assistant | :system | :developer` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `encrypted_content: String` + - `:user` - Opaque encrypted content. + - `:assistant` - - `type: :encrypted_content` + - `:system` - The type of the input item. Always `encrypted_content`. + - `:developer` - - `:encrypted_content` + - `phase: :commentary | :final_answer` - - `recipient: 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 destination agent identity. + - `:commentary` - - `type: :agent_message` + - `:final_answer` - The item type. Always `agent_message`. + - `type: :message` - - `:agent_message` + The type of the message input. Always `message`. - - `id: String` + - `:message` - The unique ID of this agent message item. +### Beta File Search Tool - - `agent: Agent{ agent_name}` +- `class BetaFileSearchTool` - 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`. - - `class MultiAgentCall` + - `:file_search` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `vector_store_ids: Array[String]` - The multi-agent action that was executed. + The IDs of the vector stores to search. - - `:spawn_agent` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `:interrupt_agent` + A filter to apply. - - `:list_agents` + - `class ComparisonFilter` - - `:send_message` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:followup_task` + - `key: String` - - `:wait_agent` + The key to compare against the value. - - `arguments: String` + - `type: :eq | :ne | :gt | 5 more` - The action arguments as a JSON string. + 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 - The unique ID linking this call to its output. + - `:eq` - - `type: :multi_agent_call` + - `:ne` - The item type. Always `multi_agent_call`. + - `:gt` - - `:multi_agent_call` + - `:gte` - - `id: String` + - `:lt` - The unique ID of this multi-agent call. + - `:lte` - - `agent: Agent{ agent_name}` + - `:in` - The agent that produced this item. + - `:nin` - - `agent_name: String` + - `value: String | Float | bool | Array[String | Float]` - The canonical name of the agent that produced this item. + The value to compare against the attribute key; supports string, number, or boolean types. - - `class MultiAgentCallOutput` + - `String = String` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `Float = Float` - The multi-agent action that produced this result. + - `UnionMember2 = bool` - - `:spawn_agent` + - `UnionMember3 = Array[String | Float]` - - `:interrupt_agent` + - `String = String` - - `:list_agents` + - `Float = Float` - - `:send_message` + - `class CompoundFilter` - - `:followup_task` + Combine multiple filters using `and` or `or`. - - `:wait_agent` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `call_id: String` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The unique ID of the multi-agent call. + - `class ComparisonFilter` - - `output: Array[Output{ text, type, annotations}]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Text output returned by the multi-agent action. + - `key: String` - - `text: String` + The key to compare against the value. - The text content. + - `type: :eq | :ne | :gt | 5 more` - - `type: :output_text` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The content type. Always `output_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 - - `:output_text` + - `:eq` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `:ne` - Citations associated with the text content. + - `:gt` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `:gte` - - `file_id: String` + - `:lt` - The ID of the file. + - `:lte` - - `filename: String` + - `:in` - The filename of the file cited. + - `:nin` - - `index: Integer` + - `value: String | Float | bool | Array[String | Float]` - The index of the file in the list of files. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: :file_citation` + - `String = String` - The citation type. Always `file_citation`. + - `Float = Float` - - `:file_citation` + - `UnionMember2 = bool` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `UnionMember3 = Array[String | Float]` - - `end_index: Integer` + - `String = String` - The index of the last character of the citation in the message. + - `Float = Float` - - `start_index: Integer` + - `UnionMember1 = untyped` - The index of the first character of the citation in the message. + - `type: :and | :or` - - `title: String` + Type of operation: `and` or `or`. - The title of the cited resource. + - `:and` - - `type: :url_citation` + - `:or` - The citation type. Always `url_citation`. + - `max_num_results: Integer` - - `:url_citation` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `url: String` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The URL of the cited resource. + Ranking options for search. - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `container_id: String` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The ID of the container. + - `embedding_weight: Float` - - `end_index: Integer` + The weight of the embedding in the reciprocal ranking fusion. - The index of the last character of the citation in the message. + - `text_weight: Float` - - `file_id: String` + The weight of the text in the reciprocal ranking fusion. - The ID of the container file. + - `ranker: :auto | :"default-2024-11-15"` - - `filename: String` + The ranker to use for the file search. - The filename of the container file cited. + - `:auto` - - `start_index: Integer` + - `:"default-2024-11-15"` - The index of the first character of the citation in the message. + - `score_threshold: Float` - - `type: :container_file_citation` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The citation type. Always `container_file_citation`. +### Beta Function Shell Tool - - `:container_file_citation` +- `class BetaFunctionShellTool` - - `type: :multi_agent_call_output` + A tool that allows the model to execute shell commands. - The item type. Always `multi_agent_call_output`. + - `type: :shell` - - `:multi_agent_call_output` + The type of the shell tool. Always `shell`. - - `id: String` + - `:shell` - The unique ID of this multi-agent call output. + - `allowed_callers: Array[:direct | :programmatic]` - - `agent: Agent{ 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: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `class ToolSearchCall` + - `class BetaContainerAuto` - - `arguments: untyped` + - `type: :container_auto` - The arguments supplied to the tool search call. + Automatically creates a container for this request - - `type: :tool_search_call` + - `:container_auto` - The item type. Always `tool_search_call`. + - `file_ids: Array[String]` - - `:tool_search_call` + An optional list of uploaded files to make available to your code. - - `id: String` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The unique ID of this tool search call. + The memory limit for the container. - - `agent: Agent{ 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"` - - `call_id: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The unique ID of the tool search call generated by the model. + Network access policy for the container. - - `execution: :server | :client` + - `class BetaContainerNetworkPolicyDisabled` - Whether tool search was executed by the server or by the client. + - `type: :disabled` - - `:server` + Disable outbound network access. Always `disabled`. - - `:client` + - `:disabled` - - `status: :in_progress | :completed | :incomplete` + - `class BetaContainerNetworkPolicyAllowlist` - The status of the tool search call. + - `allowed_domains: Array[String]` - - `:in_progress` + A list of allowed domains when type is `allowlist`. - - `:completed` + - `type: :allowlist` - - `:incomplete` + Allow outbound network access only to specified domains. Always `allowlist`. - - `class BetaResponseToolSearchOutputItemParam` + - `:allowlist` - - `tools: Array[BetaTool]` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - The loaded tool definitions returned by the tool search output. + Optional domain-scoped secrets for allowlisted domains. - - `class BetaFunctionTool` + - `domain: 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 domain associated with the secret. - `name: String` - The name of the function to call. + The name of the secret to inject for the domain. - - `parameters: Hash[Symbol, untyped]` + - `value: String` - A JSON schema object describing the parameters of the function. + The secret value to inject for the domain. - - `strict: bool` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - Whether strict parameter validation is enforced for this function tool. + An optional list of skills referenced by id or inline data. - - `type: :function` + - `class BetaSkillReference` - The type of the function tool. Always `function`. + - `skill_id: String` - - `:function` + The ID of the referenced skill. - - `allowed_callers: Array[:direct | :programmatic]` + - `type: :skill_reference` - The tool invocation context(s). + References a skill created with the /v1/skills endpoint. - - `:direct` + - `:skill_reference` - - `:programmatic` + - `version: String` - - `defer_loading: bool` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Whether this function is deferred and loaded via tool search. + - `class BetaInlineSkill` - `description: String` - A description of the function. Used by the model to determine whether or not to call the function. + The description of the skill. - - `output_schema: Hash[Symbol, untyped]` + - `name: String` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The name of the skill. - - `class BetaFileSearchTool` + - `source: BetaInlineSkillSource` - 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). + Inline skill payload - - `type: :file_search` + - `data: String` - The type of the file search tool. Always `file_search`. + Base64-encoded skill zip bundle. - - `:file_search` + - `media_type: :"application/zip"` - - `vector_store_ids: Array[String]` + The media type of the inline skill payload. Must be `application/zip`. - The IDs of the vector stores to search. + - `:"application/zip"` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `type: :base64` - A filter to apply. + The type of the inline skill source. Must be `base64`. - - `class ComparisonFilter` + - `:base64` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: :inline` - - `key: String` + Defines an inline skill for this request. - The key to compare against the value. + - `:inline` - - `type: :eq | :ne | :gt | 5 more` + - `class BetaLocalEnvironment` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: :local` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Use a local computer environment. - - `:eq` + - `:local` - - `:ne` + - `skills: Array[BetaLocalSkill]` - - `:gt` + An optional list of skills. - - `:gte` + - `description: String` - - `:lt` + The description of the skill. - - `:lte` + - `name: String` - - `:in` + The name of the skill. - - `:nin` + - `path: String` - - `value: String | Float | bool | Array[untyped]` + The path to the directory containing the skill. - The value to compare against the attribute key; supports string, number, or boolean types. + - `class BetaContainerReference` - - `String = String` + - `container_id: String` - - `Float = Float` + The ID of the referenced container. - - `UnionMember2 = bool` + - `type: :container_reference` - - `UnionMember3 = Array[untyped]` + References a container created with the /v1/containers endpoint - - `class CompoundFilter` + - `:container_reference` - Combine multiple filters using `and` or `or`. +### Beta Function Tool - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` +- `class BetaFunctionTool` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + 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). - - `class ComparisonFilter` + - `name: String` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The name of the function to call. - - `key: String` + - `parameters: Hash[Symbol, untyped]` - The key to compare against the value. + A JSON schema object describing the parameters of the function. - - `type: :eq | :ne | :gt | 5 more` + - `strict: bool` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Whether strict parameter validation is enforced for this function 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` - - `:eq` + The type of the function tool. Always `function`. - - `:ne` + - `:function` - - `:gt` + - `allowed_callers: Array[:direct | :programmatic]` - - `:gte` + The tool invocation context(s). - - `:lt` + - `:direct` - - `:lte` + - `:programmatic` - - `:in` + - `defer_loading: bool` - - `:nin` + Whether this function is deferred and loaded via tool search. - - `value: String | Float | bool | Array[untyped]` + - `description: String` - The value to compare against the attribute key; supports string, number, or boolean types. + A description of the function. Used by the model to determine whether or not to call the function. - - `String = String` + - `output_schema: Hash[Symbol, untyped]` - - `Float = Float` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `UnionMember2 = bool` +### Beta Inline Skill - - `UnionMember3 = Array[untyped]` +- `class BetaInlineSkill` - - `UnionMember1 = untyped` + - `description: String` - - `type: :and | :or` + The description of the skill. - Type of operation: `and` or `or`. + - `name: String` - - `:and` + The name of the skill. - - `:or` + - `source: BetaInlineSkillSource` - - `max_num_results: Integer` + Inline skill payload - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `data: String` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + Base64-encoded skill zip bundle. - Ranking options for search. + - `media_type: :"application/zip"` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + The media type of the inline skill payload. Must be `application/zip`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `:"application/zip"` - - `embedding_weight: Float` + - `type: :base64` - The weight of the embedding in the reciprocal ranking fusion. + The type of the inline skill source. Must be `base64`. - - `text_weight: Float` + - `:base64` - The weight of the text in the reciprocal ranking fusion. + - `type: :inline` - - `ranker: :auto | :"default-2024-11-15"` + Defines an inline skill for this request. - The ranker to use for the file search. + - `:inline` - - `:auto` +### Beta Inline Skill Source - - `:"default-2024-11-15"` +- `class BetaInlineSkillSource` - - `score_threshold: Float` + Inline skill payload - 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. + - `data: String` - - `class BetaComputerTool` + Base64-encoded skill zip bundle. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `media_type: :"application/zip"` - - `type: :computer` + The media type of the inline skill payload. Must be `application/zip`. - The type of the computer tool. Always `computer`. + - `:"application/zip"` - - `:computer` + - `type: :base64` - - `class BetaComputerUsePreviewTool` + The type of the inline skill source. Must be `base64`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:base64` - - `display_height: Integer` +### Beta Local Environment - The height of the computer display. +- `class BetaLocalEnvironment` - - `display_width: Integer` + - `type: :local` - The width of the computer display. + Use a local computer environment. - - `environment: :windows | :mac | :linux | 2 more` + - `:local` - The type of computer environment to control. + - `skills: Array[BetaLocalSkill]` - - `:windows` + An optional list of skills. - - `:mac` + - `description: String` - - `:linux` + The description of the skill. - - `:ubuntu` + - `name: String` - - `:browser` + The name of the skill. - - `type: :computer_use_preview` + - `path: String` - The type of the computer use tool. Always `computer_use_preview`. + The path to the directory containing the skill. - - `:computer_use_preview` +### Beta Local Skill - - `class BetaWebSearchTool` +- `class BetaLocalSkill` - 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). + - `description: String` - - `type: :web_search | :web_search_2025_08_26` + The description of the skill. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `name: String` - - `:web_search` + The name of the skill. - - `:web_search_2025_08_26` + - `path: String` - - `filters: Filters{ allowed_domains}` + The path to the directory containing the skill. - Filters for the search. +### Beta Namespace Tool - - `allowed_domains: Array[String]` +- `class BetaNamespaceTool` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + Groups function/custom tools under a shared namespace. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `description: String` - - `search_context_size: :low | :medium | :high` + A description of the namespace shown 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. + - `name: String` - - `:low` + The namespace name used in tool calls (for example, `crm`). - - `:medium` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `:high` + The function/custom tools available inside this namespace. - - `user_location: UserLocation{ city, country, region, 2 more}` + - `class Function` - The approximate location of the user. + - `name: String` - - `city: String` + - `type: :function` - Free text input for the city of the user, e.g. `San Francisco`. + - `:function` - - `country: String` + - `allowed_callers: Array[:direct | :programmatic]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The tool invocation context(s). - - `region: String` + - `:direct` - Free text input for the region of the user, e.g. `California`. + - `:programmatic` - - `timezone: String` + - `defer_loading: bool` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Whether this function should be deferred and discovered via tool search. - - `type: :approximate` + - `description: String` - The type of location approximation. Always `approximate`. + - `output_schema: Hash[Symbol, untyped]` - - `:approximate` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class Mcp` + - `parameters: untyped` - 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). + - `strict: bool` - - `server_label: 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. - A label for this MCP server, used to identify it in tool calls. + - `class BetaCustomTool` - - `type: :mcp` + 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 MCP tool. Always `mcp`. + - `name: String` - - `:mcp` + 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: Array[:direct | :programmatic]` @@ -27310,923 +37657,909 @@ Get a model response - `:programmatic` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - List of allowed tool names or a filter object. - - - `McpAllowedTools = Array[String]` - - A string array of allowed tool names - - - `class McpToolFilter` + - `defer_loading: bool` - A filter object to specify which tools are allowed. + Whether this tool should be deferred and discovered via tool search. - - `read_only: bool` + - `description: 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. + Optional description of the custom tool, used to provide more context. - - `tool_names: Array[String]` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - List of allowed tool names. + The input format for the custom tool. Default is unconstrained text. - - `authorization: String` + - `class 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. + Unconstrained free-form text. - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `type: :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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + Unconstrained text format. Always `text`. - Currently supported `connector_id` values are: + - `:text` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `class Grammar` - - `:connector_dropbox` + A grammar defined by the user. - - `:connector_gmail` + - `definition: String` - - `:connector_googlecalendar` + The grammar definition. - - `:connector_googledrive` + - `syntax: :lark | :regex` - - `:connector_microsoftteams` + The syntax of the grammar definition. One of `lark` or `regex`. - - `:connector_outlookcalendar` + - `:lark` - - `:connector_outlookemail` + - `:regex` - - `:connector_sharepoint` + - `type: :grammar` - - `defer_loading: bool` + Grammar format. Always `grammar`. - Whether this MCP tool is deferred and discovered via tool search. + - `:grammar` - - `headers: Hash[Symbol, String]` + - `type: :namespace` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The type of the tool. Always `namespace`. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:namespace` - Specify which of the MCP server's tools require approval. +### Beta Response - - `class McpToolApprovalFilter` +- `class BetaResponse` - 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: Always{ read_only, tool_names}` + Unique identifier for this Response. - A filter object to specify which tools are allowed. + - `created_at: Float` - - `read_only: bool` + Unix timestamp (in seconds) of when this Response was created. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `error: BetaResponseError` - - `tool_names: Array[String]` + An error object returned when the model fails to generate a Response. - List of allowed tool names. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `never: Never{ read_only, tool_names}` + The error code for the response. - A filter object to specify which tools are allowed. + - `:server_error` - - `read_only: bool` + - `:rate_limit_exceeded` - Indicates whether or not a tool modifies data or is read-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_prompt` - - `tool_names: Array[String]` + - `:bio_policy` - List of allowed tool names. + - `:vector_store_timeout` - - `McpToolApprovalSetting = :always | :never` + - `:invalid_image` - 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. + - `:invalid_image_format` - - `:always` + - `:invalid_base64_image` - - `:never` + - `:invalid_image_url` - - `server_description: String` + - `:image_too_large` - Optional description of the MCP server, used to provide more context. + - `:image_too_small` - - `server_url: String` + - `:image_parse_error` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:image_content_policy_violation` - - `tunnel_id: String` + - `:invalid_image_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. + - `:image_file_too_large` - - `class CodeInterpreter` + - `:unsupported_image_media_type` - A tool that runs Python code to help generate a response to a prompt. + - `:empty_image_file` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `:failed_to_download_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_file_not_found` - - `String = String` + - `message: String` - The container ID. + A human-readable description of the error. - - `class CodeInterpreterToolAuto` + - `incomplete_details: IncompleteDetails{ reason}` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Details about why the response is incomplete. - - `type: :auto` + - `reason: :max_output_tokens | :content_filter` - Always `auto`. + The reason why the response is incomplete. - - `:auto` + - `:max_output_tokens` - - `file_ids: Array[String]` + - `:content_filter` - An optional list of uploaded files to make available to your code. + - `instructions: String | Array[BetaResponseInputItem]` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + A system (or developer) message inserted into the model's context. - The memory limit for the code interpreter container. + 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. - - `:"1g"` + - `String = String` - - `:"4g"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `:"16g"` + - `InputItemList = Array[BetaResponseInputItem]` - - `:"64g"` + A list of one or many input items to the model, containing + different content types. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `class BetaEasyInputMessage` - Network access policy for the container. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `class BetaContainerNetworkPolicyDisabled` + - `content: String | BetaResponseInputMessageContentList` - - `type: :disabled` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Disable outbound network access. Always `disabled`. + - `String = String` - - `:disabled` + A text input to the model. - - `class BetaContainerNetworkPolicyAllowlist` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `allowed_domains: Array[String]` + A list of one or many input items to the model, containing different content + types. - A list of allowed domains when type is `allowlist`. + - `class BetaResponseInputText` - - `type: :allowlist` + A text input to the model. - Allow outbound network access only to specified domains. Always `allowlist`. + - `text: String` - - `:allowlist` + The text input to the model. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `type: :input_text` - Optional domain-scoped secrets for allowlisted domains. + The type of the input item. Always `input_text`. - - `domain: String` + - `:input_text` - The domain associated with the secret. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 secret to inject for the domain. + - `mode: :explicit` - - `value: String` + The breakpoint mode. Always `explicit`. - The secret value to inject for the domain. + - `:explicit` - - `type: :code_interpreter` + - `class BetaResponseInputImage` - The type of the code interpreter tool. Always `code_interpreter`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:code_interpreter` + - `detail: :low | :high | :auto | :original` - - `allowed_callers: Array[:direct | :programmatic]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The tool invocation context(s). + - `:low` - - `:direct` + - `:high` - - `:programmatic` + - `:auto` - - `class ProgrammaticToolCalling` + - `:original` - - `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` - - `class ImageGeneration` + - `file_id: 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` + - `image_url: String` - The type of the image generation tool. Always `image_generation`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `:image_generation` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `action: :generate | :edit | :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. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `mode: :explicit` - - `:generate` + The breakpoint mode. Always `explicit`. - - `:edit` + - `:explicit` - - `:auto` + - `class BetaResponseInputFile` - - `background: :transparent | :opaque | :auto` + A file input to the model. - 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: :input_file` - `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 `input_file`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `:input_file` - - `:transparent` + - `detail: :auto | :low | :high` - - `:opaque` + 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` - - `input_fidelity: :high | :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`. + - `:low` - `:high` - - `:low` - - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `file_data: String` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The content of the file to be sent to the model. - `file_id: String` - File ID for the mask image. + The ID of the file to be sent to the model. - - `image_url: String` + - `file_url: String` - Base64-encoded mask image. + The URL of the file to be sent to the model. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `filename: String` - The image generation model to use. Default: `gpt-image-1`. + The name of the file to be sent to the model. - - `String = String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. - The image generation model to use. Default: `gpt-image-1`. + - `mode: :explicit` - - `:"gpt-image-1"` + The breakpoint mode. Always `explicit`. - - `:"gpt-image-1-mini"` + - `:explicit` - - `:"gpt-image-2"` + - `role: :user | :assistant | :system | :developer` - - `:"gpt-image-2-2026-04-21"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `:"gpt-image-1.5"` + - `:user` - - `:"chatgpt-image-latest"` + - `:assistant` - - `moderation: :auto | :low` + - `:system` - Moderation level for the generated image. Default: `auto`. + - `:developer` - - `:auto` + - `phase: :commentary | :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. - - `output_compression: Integer` + - `:commentary` - Compression level for the output image. Default: 100. + - `:final_answer` - - `output_format: :png | :webp | :jpeg` + - `type: :message` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the message input. Always `message`. - - `:png` + - `:message` - - `:webp` + - `class Message` - - `:jpeg` + 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. - - `partial_images: Integer` + - `content: BetaResponseInputMessageContentList` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A list of one or many input items to the model, containing different content + types. - - `quality: :low | :medium | :high | :auto` + - `role: :user | :system | :developer` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The role of the message input. One of `user`, `system`, or `developer`. - - `:low` + - `:user` - - `:medium` + - `:system` - - `:high` + - `:developer` - - `:auto` + - `agent: Agent{ agent_name}` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 = String` + The canonical name of the agent that produced this item. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `status: :in_progress | :completed | :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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:"1024x1024"` + - `:in_progress` - - `:"1024x1536"` + - `:completed` - - `:"1536x1024"` + - `:incomplete` - - `:auto` + - `type: :message` - - `class LocalShell` + The type of the message input. Always set to `message`. - A tool that allows the model to execute shell commands in a local environment. + - `:message` - - `type: :local_shell` + - `class BetaResponseOutputMessage` - The type of the local shell tool. Always `local_shell`. + An output message from the model. - - `:local_shell` + - `id: String` - - `class BetaFunctionShellTool` + The unique ID of the output message. - A tool that allows the model to execute shell commands. + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - - `type: :shell` + The content of the output message. - The type of the shell tool. Always `shell`. + - `class BetaResponseOutputText` - - `:shell` + A text output from the model. - - `allowed_callers: Array[:direct | :programmatic]` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - The tool invocation context(s). + The annotations of the text output. - - `:direct` + - `class FileCitation` - - `:programmatic` + A citation to a file. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `file_id: String` - - `class BetaContainerAuto` + The ID of the file. - - `type: :container_auto` + - `filename: String` - Automatically creates a container for this request + The filename of the file cited. - - `:container_auto` + - `index: Integer` - - `file_ids: Array[String]` + The index of the file in the list of files. - An optional list of uploaded files to make available to your code. + - `type: :file_citation` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + The type of the file citation. Always `file_citation`. - The memory limit for the container. + - `:file_citation` - - `:"1g"` + - `class URLCitation` - - `:"4g"` + A citation for a web resource used to generate a model response. - - `:"16g"` + - `end_index: Integer` - - `:"64g"` + The index of the last character of the URL citation in the message. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `start_index: Integer` - Network access policy for the container. + The index of the first character of the URL citation in the message. - - `class BetaContainerNetworkPolicyDisabled` + - `title: String` - - `class BetaContainerNetworkPolicyAllowlist` + The title of the web resource. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `type: :url_citation` - An optional list of skills referenced by id or inline data. + The type of the URL citation. Always `url_citation`. - - `class BetaSkillReference` + - `:url_citation` - - `skill_id: String` + - `url: String` - The ID of the referenced skill. + The URL of the web resource. - - `type: :skill_reference` + - `class ContainerFileCitation` - References a skill created with the /v1/skills endpoint. + A citation for a container file used to generate a model response. - - `:skill_reference` + - `container_id: String` - - `version: String` + The ID of the container file. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `end_index: Integer` - - `class BetaInlineSkill` + The index of the last character of the container file citation in the message. - - `description: String` + - `file_id: String` - The description of the skill. + The ID of the file. - - `name: String` + - `filename: String` - The name of the skill. + The filename of the container file cited. - - `source: BetaInlineSkillSource` + - `start_index: Integer` - Inline skill payload + The index of the first character of the container file citation in the message. - - `data: String` + - `type: :container_file_citation` - Base64-encoded skill zip bundle. + The type of the container file citation. Always `container_file_citation`. - - `media_type: :"application/zip"` + - `:container_file_citation` - The media type of the inline skill payload. Must be `application/zip`. + - `class FilePath` - - `:"application/zip"` + A path to a file. - - `type: :base64` + - `file_id: String` - The type of the inline skill source. Must be `base64`. + The ID of the file. - - `:base64` + - `index: Integer` - - `type: :inline` + The index of the file in the list of files. - Defines an inline skill for this request. + - `type: :file_path` - - `:inline` + The type of the file path. Always `file_path`. - - `class BetaLocalEnvironment` + - `:file_path` - - `type: :local` + - `text: String` - Use a local computer environment. + The text output from the model. - - `:local` + - `type: :output_text` - - `skills: Array[BetaLocalSkill]` + The type of the output text. Always `output_text`. - An optional list of skills. + - `:output_text` - - `description: String` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - The description of the skill. + - `token: String` - - `name: String` + - `bytes: Array[Integer]` - The name of the skill. + - `logprob: Float` - - `path: String` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - The path to the directory containing the skill. + - `token: String` - - `class BetaContainerReference` + - `bytes: Array[Integer]` - - `container_id: String` + - `logprob: Float` - The ID of the referenced container. + - `class BetaResponseOutputRefusal` - - `type: :container_reference` + A refusal from the model. - References a container created with the /v1/containers endpoint + - `refusal: String` - - `:container_reference` + The refusal explanation from the model. - - `class BetaCustomTool` + - `type: :refusal` - 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 refusal. Always `refusal`. - - `name: String` + - `:refusal` - The name of the custom tool, used to identify it in tool calls. + - `role: :assistant` - - `type: :custom` + The role of the output message. Always `assistant`. - The type of the custom tool. Always `custom`. + - `:assistant` - - `:custom` + - `status: :in_progress | :completed | :incomplete` - - `allowed_callers: Array[:direct | :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: bool` + - `type: :message` - Whether this tool should be deferred and discovered via tool search. + The type of the output message. Always `message`. - - `description: String` + - `:message` - Optional description of the custom tool, used to provide more context. + - `agent: Agent{ agent_name}` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + The agent that produced this item. - The input format for the custom tool. Default is unconstrained text. + - `agent_name: String` - - `class Text` + The canonical name of the agent that produced this item. - Unconstrained free-form text. + - `phase: :commentary | :final_answer` - - `type: :text` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Unconstrained text format. Always `text`. + - `:commentary` - - `:text` + - `:final_answer` - - `class Grammar` + - `class BetaResponseFileSearchToolCall` - A grammar defined by the user. + 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. - - `definition: String` + - `id: String` - The grammar definition. + The unique ID of the file search tool call. - - `syntax: :lark | :regex` + - `queries: Array[String]` - The syntax of the grammar definition. One of `lark` or `regex`. + The queries used to search for files. - - `:lark` + - `status: :in_progress | :searching | :completed | 2 more` - - `:regex` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: :grammar` + - `:in_progress` - Grammar format. Always `grammar`. + - `:searching` - - `:grammar` + - `:completed` - - `class BetaNamespaceTool` + - `:incomplete` - Groups function/custom tools under a shared namespace. + - `:failed` - - `description: String` + - `type: :file_search_call` - A description of the namespace shown to the model. + The type of the file search tool call. Always `file_search_call`. - - `name: String` + - `:file_search_call` - The namespace name used in tool calls (for example, `crm`). + - `agent: Agent{ agent_name}` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + The agent that produced this item. - The function/custom tools available inside this namespace. + - `agent_name: String` - - `class Function` + The canonical name of the agent that produced this item. - - `name: String` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - `type: :function` + The results of the file search tool call. - - `:function` + - `attributes: Hash[Symbol, String | Float | bool]` - - `allowed_callers: Array[:direct | :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 = String` - - `:direct` + - `Float = Float` - - `:programmatic` + - `UnionMember2 = bool` - - `defer_loading: bool` + - `file_id: String` - Whether this function should be deferred and discovered via tool search. + The unique ID of the file. - - `description: String` + - `filename: String` + + The name of the file. + + - `score: Float` + + The relevance score of the file - a value between 0 and 1. - - `output_schema: Hash[Symbol, untyped]` + - `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 that was retrieved from the file. - - `parameters: untyped` + - `class BetaResponseComputerToolCall` - - `strict: bool` + 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 to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `id: String` - - `class BetaCustomTool` + The unique ID of the computer 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) + - `call_id: String` - - `type: :namespace` + An identifier used when responding to the tool call with output. - The type of the tool. Always `namespace`. + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `:namespace` + The pending safety checks for the computer call. - - `class BetaToolSearchTool` + - `id: String` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the pending safety check. - - `type: :tool_search` + - `code: String` - The type of the tool. Always `tool_search`. + The type of the pending safety check. - - `:tool_search` + - `message: String` - - `description: String` + Details about the pending safety check. - Description shown to the model for a client-executed tool search tool. + - `status: :in_progress | :completed | :incomplete` - - `execution: :server | :client` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether tool search is executed by the server or by the client. + - `:in_progress` - - `:server` + - `:completed` - - `:client` + - `:incomplete` - - `parameters: untyped` + - `type: :computer_call` - Parameter schema for a client-executed tool search tool. + The type of the computer call. Always `computer_call`. - - `class BetaWebSearchPreviewTool` + - `:computer_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). + - `action: BetaComputerAction` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + A click action. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class Click` - - `:web_search_preview` + A click action. - - `:web_search_preview_2025_03_11` + - `button: :left | :right | :wheel | 2 more` - - `search_content_types: Array[:text | :image]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `:text` + - `:left` - - `:image` + - `:right` - - `search_context_size: :low | :medium | :high` + - `:wheel` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `:back` - - `:low` + - `:forward` - - `:medium` + - `type: :click` - - `:high` + Specifies the event type. For a click action, this property is always `click`. - - `user_location: UserLocation{ type, city, country, 2 more}` + - `:click` - The user's location. + - `x: Integer` - - `type: :approximate` + The x-coordinate where the click occurred. - The type of location approximation. Always `approximate`. + - `y_: Integer` - - `:approximate` + The y-coordinate where the click occurred. - - `city: String` + - `keys: Array[String]` - Free text input for the city of the user, e.g. `San Francisco`. + The keys being held while clicking. - - `country: String` + - `class DoubleClick` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A double click action. - - `region: String` + - `keys: Array[String]` - Free text input for the region of the user, e.g. `California`. + The keys being held while double-clicking. - - `timezone: String` + - `type: :double_click` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `class BetaApplyPatchTool` + - `:double_click` - Allows the assistant to create, delete, or update files using unified diffs. + - `x: Integer` - - `type: :apply_patch` + The x-coordinate where the double click occurred. - The type of the tool. Always `apply_patch`. + - `y_: Integer` - - `:apply_patch` + The y-coordinate where the double click occurred. - - `allowed_callers: Array[:direct | :programmatic]` + - `class Drag` - The tool invocation context(s). + A drag action. - - `:direct` + - `path: Array[Path{ x, y_}]` - - `:programmatic` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `type: :tool_search_output` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The item type. Always `tool_search_output`. + - `x: Integer` - - `:tool_search_output` + The x-coordinate. - - `id: String` + - `y_: Integer` - The unique ID of this tool search output. + The y-coordinate. - - `agent: Agent{ agent_name}` + - `type: :drag` - The agent that produced this item. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `agent_name: String` + - `:drag` - The canonical name of the agent that produced this item. + - `keys: Array[String]` - - `call_id: String` + The keys being held while dragging the mouse. - The unique ID of the tool search call generated by the model. + - `class Keypress` - - `execution: :server | :client` + A collection of keypresses the model would like to perform. - Whether tool search was executed by the server or by the client. + - `keys: Array[String]` - - `:server` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `:client` + - `type: :keypress` - - `status: :in_progress | :completed | :incomplete` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The status of the tool search output. + - `:keypress` - - `:in_progress` + - `class Move` - - `:completed` + A mouse move action. - - `:incomplete` + - `type: :move` - - `class AdditionalTools` + Specifies the event type. For a move action, this property is always set to `move`. - - `role: :developer` + - `:move` - The role that provided the additional tools. Only `developer` is supported. + - `x: Integer` - - `:developer` + The x-coordinate to move to. - - `tools: Array[BetaTool]` + - `y_: Integer` - A list of additional tools made available at this item. + The y-coordinate to move to. - - `class BetaFunctionTool` + - `keys: Array[String]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The keys being held while moving the mouse. - - `class BetaFileSearchTool` + - `class Screenshot` - 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. - - `class BetaComputerTool` + - `type: :screenshot` - 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 screenshot action, this property is always set to `screenshot`. - - `class BetaComputerUsePreviewTool` + - `:screenshot` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Scroll` - - `class BetaWebSearchTool` + A scroll action. - 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). + - `scroll_x: Integer` - - `class Mcp` + 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: Integer` - - `class CodeInterpreter` + The vertical scroll distance. - A tool that runs Python code to help generate a response to a prompt. + - `type: :scroll` - - `class ProgrammaticToolCalling` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class ImageGeneration` + - `:scroll` - A tool that generates images using the GPT image models. + - `x: Integer` - - `class LocalShell` + The x-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands in a local environment. + - `y_: Integer` - - `class BetaFunctionShellTool` + The y-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands. + - `keys: Array[String]` - - `class BetaCustomTool` + The keys being held while scrolling. - 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) + - `class Type` - - `class BetaNamespaceTool` + An action to type in text. - Groups function/custom tools under a shared namespace. + - `text: String` - - `class BetaToolSearchTool` + The text to type. - Hosted or BYOT tool search configuration for deferred tools. + - `type: :type` - - `class BetaWebSearchPreviewTool` + Specifies the event type. For a type action, this property is always set to `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). + - `:type` - - `class BetaApplyPatchTool` + - `class Wait` - Allows the assistant to create, delete, or update files using unified diffs. + A wait action. - - `type: :additional_tools` + - `type: :wait` - The item type. Always `additional_tools`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `:additional_tools` + - `:wait` - - `id: String` + - `actions: BetaComputerActionList` - The unique ID of this additional tools item. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `agent: Agent{ agent_name}` + - `class Click` - The agent that produced this item. + A click action. - - `agent_name: String` + - `class DoubleClick` - The canonical name of the agent that produced this item. + A double click action. - - `class BetaResponseReasoningItem` + - `class Drag` - 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 drag action. - - `id: String` + - `class Keypress` - The unique identifier of the reasoning content. + A collection of keypresses the model would like to perform. - - `summary: Array[Summary{ text, type}]` + - `class Move` - Reasoning summary content. + A mouse move action. - - `text: String` + - `class Screenshot` - A summary of the reasoning output from the model so far. + A screenshot action. - - `type: :summary_text` + - `class Scroll` - The type of the object. Always `summary_text`. + A scroll action. - - `:summary_text` + - `class Type` - - `type: :reasoning` + An action to type in text. - The type of the object. Always `reasoning`. + - `class Wait` - - `:reasoning` + A wait action. - `agent: Agent{ agent_name}` @@ -28236,53 +38569,58 @@ Get a model response The canonical name of the agent that produced this item. - - `content: Array[Content{ text, type}]` - - Reasoning text content. + - `class ComputerCallOutput` - - `text: String` + The output of a computer tool call. - The reasoning text from the model. + - `call_id: String` - - `type: :reasoning_text` + The ID of the computer tool call that produced the output. - The type of the reasoning text. Always `reasoning_text`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `:reasoning_text` + A computer screenshot image used with the computer use tool. - - `encrypted_content: String` + - `type: :computer_screenshot` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `status: :in_progress | :completed | :incomplete` + - `:computer_screenshot` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_id: String` - - `:in_progress` + The identifier of an uploaded file that contains the screenshot. - - `:completed` + - `image_url: String` - - `:incomplete` + The URL of the screenshot image. - - `class BetaResponseCompactionItemParam` + - `type: :computer_call_output` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The type of the computer tool call output. Always `computer_call_output`. - - `encrypted_content: String` + - `:computer_call_output` - The encrypted content of the compaction summary. + - `id: String` - - `type: :compaction` + The ID of the computer tool call output. - The type of the item. Always `compaction`. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:compaction` + The safety checks reported by the API that have been acknowledged by the developer. - `id: String` - The ID of the compaction item. + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -28292,112 +38630,111 @@ Get a model response The canonical name of the agent that produced this item. - - `class ImageGenerationCall` + - `status: :in_progress | :completed | :incomplete` - An image generation request made by the model. + 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 image generation call. + - `:completed` - - `result: String` + - `:incomplete` - The generated image encoded in base64. + - `class BetaResponseFunctionWebSearch` - - `status: :in_progress | :completed | :generating | :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. - The status of the image generation call. + - `id: String` - - `:in_progress` + The unique ID of the web search tool call. - - `:completed` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `:generating` + 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). - - `:failed` + - `class Search` - - `type: :image_generation_call` + Action type "search" - Performs a web search query. - The type of the image generation call. Always `image_generation_call`. + - `type: :search` - - `:image_generation_call` + The action type. - - `agent: Agent{ agent_name}` + - `:search` - The agent that produced this item. + - `queries: Array[String]` - - `agent_name: String` + The search queries. - The canonical name of the agent that produced this item. + - `query: String` - - `class BetaResponseCodeInterpreterToolCall` + The search query. - A tool call to run code. + - `sources: Array[Source{ type, url}]` - - `id: String` + The sources used in the search. - The unique ID of the code interpreter tool call. + - `type: :url` - - `code: String` + The type of source. Always `url`. - The code to run, or null if not available. + - `:url` - - `container_id: String` + - `url: String` - The ID of the container used to run the code. + The URL of the source. - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `class OpenPage` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Action type "open_page" - Opens a specific URL from search results. - - `class Logs` + - `type: :open_page` - The logs output from the code interpreter. + The action type. - - `logs: String` + - `:open_page` - The logs output from the code interpreter. + - `url: String` - - `type: :logs` + The URL opened by the model. - The type of the output. Always `logs`. + - `class FindInPage` - - `:logs` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `class Image` + - `pattern: String` - The image output from the code interpreter. + The pattern or text to search for within the page. - - `type: :image` + - `type: :find_in_page` - The type of the output. Always `image`. + The action type. - - `:image` + - `:find_in_page` - `url: String` - The URL of the image output from the code interpreter. + The URL of the page searched for the pattern. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `status: :in_progress | :searching | :completed | :failed` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the web search tool call. - `:in_progress` - - `:completed` - - - `:incomplete` + - `:searching` - - `:interpreting` + - `:completed` - `:failed` - - `type: :code_interpreter_call` + - `type: :web_search_call` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the web search tool call. Always `web_search_call`. - - `:code_interpreter_call` + - `:web_search_call` - `agent: Agent{ agent_name}` @@ -28407,63 +38744,32 @@ Get a model response The canonical name of the agent that produced this item. - - `class LocalShellCall` - - A tool call to run a command on the local shell. - - - `id: String` - - The unique ID of the local shell call. - - - `action: Action{ command, env, type, 3 more}` - - Execute a shell command on the server. - - - `command: Array[String]` - - The command to run. - - - `env: Hash[Symbol, String]` - - Environment variables to set for the command. - - - `type: :exec` - - The type of the local shell action. Always `exec`. - - - `:exec` - - - `timeout_ms: Integer` - - Optional timeout in milliseconds for the command. - - - `user: String` + - `class BetaResponseFunctionToolCall` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: String` + - `arguments: String` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: String` - The unique ID of the local shell tool call generated by the model. - - - `status: :in_progress | :completed | :incomplete` + The unique ID of the function tool call generated by the model. - The status of the local shell 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`. - - `type: :local_shell_call` + - `:function_call` - The type of the local shell call. Always `local_shell_call`. + - `id: String` - - `:local_shell_call` + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -28473,35 +38779,34 @@ Get a model response The canonical name of the agent that produced this item. - - `class LocalShellCallOutput` - - The output of a local shell tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class Direct` - - `output: String` + - `type: :direct` - A JSON string of the output of the local shell tool call. + - `:direct` - - `type: :local_shell_call_output` + - `class Program` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: String` - - `:local_shell_call_output` + The call ID of the program item that produced this tool call. - - `agent: Agent{ agent_name}` + - `type: :program` - The agent that produced this item. + - `:program` - - `agent_name: String` + - `namespace: String` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -28509,147 +38814,145 @@ Get a model response - `:incomplete` - - `class ShellCall` - - A tool representing a request to execute one or more shell commands. + - `class FunctionCallOutput` - - `action: Action{ commands, max_output_length, timeout_ms}` + The output of a function tool call. - The shell commands and limits that describe how to run the tool call. + - `call_id: String` - - `commands: Array[String]` + The unique ID of the function tool call generated by the model. - Ordered shell commands for the execution environment to run. + - `output: String | BetaResponseFunctionCallOutputItemList` - - `max_output_length: Integer` + Text, image, or file output of the function tool call. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `String = String` - - `timeout_ms: Integer` + A JSON string of the output of the function tool call. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `call_id: String` + An array of content outputs (text, image, file) for the function tool call. - The unique ID of the shell tool call generated by the model. + - `class BetaResponseInputTextContent` - - `type: :shell_call` + A text input to the model. - The type of the item. Always `shell_call`. + - `text: String` - - `:shell_call` + The text input to the model. - - `id: String` + - `type: :input_text` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the input item. Always `input_text`. - - `agent: Agent{ agent_name}` + - `:input_text` - The agent that produced this item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `agent_name: String` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: :explicit` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `:explicit` - - `class Direct` + - `class BetaResponseInputImageContent` - - `type: :direct` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The caller type. Always `direct`. + - `type: :input_image` - - `:direct` + The type of the input item. Always `input_image`. - - `class Program` + - `:input_image` - - `caller_id: String` + - `detail: :low | :high | :auto | :original` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :program` + - `:low` - The caller type. Always `program`. + - `:high` - - `:program` + - `:auto` - - `environment: BetaLocalEnvironment | BetaContainerReference` + - `:original` - The environment to execute the shell commands in. + - `file_id: String` - - `class BetaLocalEnvironment` + The ID of the file to be sent to the model. - - `class BetaContainerReference` + - `image_url: String` - - `status: :in_progress | :completed | :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 shell call. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - `class ShellCallOutput` + - `:explicit` - The streamed output items emitted by a shell tool call. + - `class BetaResponseInputFileContent` - - `call_id: String` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: :input_file` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + The type of the input item. Always `input_file`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `:input_file` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `detail: :auto | :low | :high` - The exit or timeout outcome associated with this shell 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`. - - `class Timeout` + - `:auto` - Indicates that the shell call exceeded its configured time limit. + - `:low` - - `type: :timeout` + - `:high` - The outcome type. Always `timeout`. + - `file_data: String` - - `:timeout` + The base64-encoded data of the file to be sent to the model. - - `class Exit` + - `file_id: String` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `exit_code: Integer` + - `file_url: String` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `type: :exit` + - `filename: String` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `:exit` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `stderr: 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. - Captured stderr output for the shell call. + - `mode: :explicit` - - `stdout: String` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `:explicit` - - `type: :shell_call_output` + - `type: :function_call_output` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `:shell_call_output` + - `:function_call_output` - `id: String` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -28683,13 +38986,9 @@ Get a model response - `:program` - - `max_output_length: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `status: :in_progress | :completed | :incomplete` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -28697,85 +38996,97 @@ Get a model response - `:incomplete` - - `class ApplyPatchCall` + - `class AgentMessage` - A tool call representing a request to create, delete, or update files using diff patches. + A message routed between agents. - - `call_id: String` + - `author: String` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class CreateFile` + - `class BetaResponseInputTextContent` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `diff: String` + - `class BetaResponseInputImageContent` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `path: String` + - `class EncryptedContent` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: :create_file` + - `encrypted_content: String` - The operation type. Always `create_file`. + Opaque encrypted content. - - `:create_file` + - `type: :encrypted_content` - - `class DeleteFile` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `:encrypted_content` - - `path: String` + - `recipient: String` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `type: :delete_file` + - `type: :agent_message` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `:delete_file` + - `:agent_message` - - `class UpdateFile` + - `id: String` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `diff: String` + - `agent: Agent{ agent_name}` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `path: String` + - `agent_name: String` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `type: :update_file` + - `class MultiAgentCall` - The operation type. Always `update_file`. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:update_file` + The multi-agent action that was executed. - - `status: :in_progress | :completed` + - `:spawn_agent` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:interrupt_agent` - - `:in_progress` + - `:list_agents` - - `:completed` + - `:send_message` - - `type: :apply_patch_call` + - `:followup_task` - The type of the item. Always `apply_patch_call`. + - `:wait_agent` - - `:apply_patch_call` + - `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: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - `agent: Agent{ agent_name}` @@ -28785,129 +39096,127 @@ Get a model response The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. + - `class MultiAgentCallOutput` - - `class Direct` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :direct` + The multi-agent action that produced this result. - The caller type. Always `direct`. + - `:spawn_agent` - - `:direct` + - `:interrupt_agent` - - `class Program` + - `: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. - - `class ApplyPatchCallOutput` + - `output: Array[Output{ text, type, annotations}]` - The streamed output emitted by an apply patch tool call. + Text output returned by the multi-agent action. - - `call_id: String` + - `text: String` - The unique ID of the apply patch tool call generated by the model. + The text content. - - `status: :completed | :failed` + - `type: :output_text` - The status of the apply patch tool call output. One of `completed` or `failed`. + The content type. Always `output_text`. - - `:completed` + - `:output_text` - - `:failed` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `type: :apply_patch_call_output` + Citations associated with the text content. - The type of the item. Always `apply_patch_call_output`. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `:apply_patch_call_output` + - `file_id: String` - - `id: 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: Agent{ agent_name}` + The filename of the file cited. - The agent that produced this item. + - `index: Integer` - - `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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The citation type. Always `file_citation`. - The execution context that produced this tool call. + - `:file_citation` - - `class Direct` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `type: :direct` + - `end_index: Integer` - The caller type. Always `direct`. + The index of the last character of the citation in the message. - - `:direct` + - `start_index: Integer` - - `class Program` + The index of the first character of the citation in the message. - - `caller_id: String` + - `title: String` - The call ID of the program item that produced this tool call. + The title of the cited resource. - - `type: :program` + - `type: :url_citation` - The caller type. Always `program`. + The citation type. Always `url_citation`. - - `:program` + - `:url_citation` - - `output: String` + - `url: String` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The URL of the cited resource. - - `class McpListTools` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - A list of tools available on an MCP server. + - `container_id: String` - - `id: String` + The ID of the container. - The unique ID of the list. + - `end_index: Integer` - - `server_label: String` + The index of the last character of the citation in the message. - The label of the MCP server. + - `file_id: String` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + The ID of the container file. - The tools available on the server. + - `filename: String` - - `input_schema: untyped` + The filename of the container file cited. - The JSON schema describing the tool's input. + - `start_index: Integer` - - `name: String` + The index of the first character of the citation in the message. - The name of the tool. + - `type: :container_file_citation` - - `annotations: untyped` + The citation type. Always `container_file_citation`. - Additional annotations about the tool. + - `:container_file_citation` - - `description: String` + - `type: :multi_agent_call_output` - The description of the tool. + The item type. Always `multi_agent_call_output`. - - `type: :mcp_list_tools` + - `:multi_agent_call_output` - The type of the item. Always `mcp_list_tools`. + - `id: String` - - `:mcp_list_tools` + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -28917,35 +39226,21 @@ Get a model response The canonical name of the agent that produced this item. - - `error: String` - - Error message if the server could not list tools. - - - `class McpApprovalRequest` - - 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. + - `class ToolSearchCall` - - `name: String` + - `arguments: untyped` - The name of the tool to run. + The arguments supplied to the tool search call. - - `server_label: String` + - `type: :tool_search_call` - The label of the MCP server making the request. + The item type. Always `tool_search_call`. - - `type: :mcp_approval_request` + - `:tool_search_call` - The type of the item. Always `mcp_approval_request`. + - `id: String` - - `:mcp_approval_request` + The unique ID of this tool search call. - `agent: Agent{ agent_name}` @@ -28955,1106 +39250,1137 @@ Get a model response The canonical name of the agent that produced this item. - - `class McpApprovalResponse` + - `call_id: String` - A response to an MCP approval request. + The unique ID of the tool search call generated by the model. - - `approval_request_id: String` + - `execution: :server | :client` - The ID of the approval request being answered. + Whether tool search was executed by the server or by the client. - - `approve: bool` + - `:server` - Whether the request was approved. + - `:client` - - `type: :mcp_approval_response` + - `status: :in_progress | :completed | :incomplete` - The type of the item. Always `mcp_approval_response`. + The status of the tool search call. - - `:mcp_approval_response` + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of the approval response + - `:incomplete` - - `agent: Agent{ agent_name}` + - `class BetaResponseToolSearchOutputItemParam` - The agent that produced this item. + - `tools: Array[BetaTool]` - - `agent_name: String` + The loaded tool definitions returned by the tool search output. - The canonical name of the agent that produced this item. + - `class BetaFunctionTool` - - `reason: String` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Optional reason for the decision. + - `name: String` - - `class McpCall` + The name of the function to call. - An invocation of a tool on an MCP server. + - `parameters: Hash[Symbol, untyped]` - - `id: String` + A JSON schema object describing the parameters of the function. - The unique ID of the tool call. + - `strict: bool` - - `arguments: String` + Whether strict parameter validation is enforced for this function tool. - A JSON string of the arguments passed to the tool. + - `type: :function` - - `name: String` + The type of the function tool. Always `function`. - The name of the tool that was run. + - `:function` - - `server_label: String` + - `allowed_callers: Array[:direct | :programmatic]` - The label of the MCP server running the tool. + The tool invocation context(s). - - `type: :mcp_call` + - `:direct` - The type of the item. Always `mcp_call`. + - `:programmatic` - - `:mcp_call` + - `defer_loading: bool` - - `agent: Agent{ agent_name}` + Whether this function is deferred and loaded via tool search. - The agent that produced this item. + - `description: 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: Hash[Symbol, untyped]` - - `approval_request_id: String` + A JSON schema object describing the JSON value encoded in string outputs for this 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. + - `class BetaFileSearchTool` - - `error: 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 error from the tool call, if any. + - `type: :file_search` - - `output: String` + The type of the file search tool. Always `file_search`. - The output from the tool call. + - `:file_search` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `vector_store_ids: Array[String]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The IDs of the vector stores to search. - - `:in_progress` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `:completed` + A filter to apply. - - `:incomplete` + - `class ComparisonFilter` - - `:calling` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:failed` + - `key: String` + + The key to compare against the value. + + - `type: :eq | :ne | :gt | 5 more` - - `class BetaResponseCustomToolCallOutput` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The output of a custom tool call from your code, being sent back 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 - - `call_id: String` + - `:eq` - The call ID, used to map this custom tool call output to a custom tool call. + - `:ne` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:gt` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `:gte` - - `String = String` + - `:lt` - A string of the output of the custom tool call. + - `:lte` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:in` - Text, image, or file output of the custom tool call. + - `:nin` - - `class BetaResponseInputText` + - `value: String | Float | bool | Array[String | Float]` - A text input to the model. + The value to compare against the attribute key; supports string, number, or boolean types. - - `class BetaResponseInputImage` + - `String = String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Float = Float` - - `class BetaResponseInputFile` + - `UnionMember2 = bool` - A file input to the model. + - `UnionMember3 = Array[String | Float]` - - `type: :custom_tool_call_output` + - `String = String` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `Float = Float` - - `:custom_tool_call_output` + - `class CompoundFilter` - - `id: String` + Combine multiple filters using `and` or `or`. - The unique ID of the custom tool call output in the OpenAI platform. + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `agent: Agent{ agent_name}` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The agent that produced this item. + - `class ComparisonFilter` - - `agent_name: String` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The canonical name of the agent that produced this item. + - `key: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The key to compare against the value. - The execution context that produced this tool call. + - `type: :eq | :ne | :gt | 5 more` - - `class Direct` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: :direct` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The caller type. Always `direct`. + - `:eq` - - `:direct` + - `:ne` - - `class Program` + - `:gt` - - `caller_id: String` + - `:gte` - The call ID of the program item that produced this tool call. + - `:lt` - - `type: :program` + - `:lte` - The caller type. Always `program`. + - `:in` - - `:program` + - `:nin` - - `class BetaResponseCustomToolCall` + - `value: String | Float | bool | Array[String | Float]` - A call to a custom tool created by the model. + The value to compare against the attribute key; supports string, number, or boolean types. - - `call_id: String` + - `String = String` - An identifier used to map this custom tool call to a tool call output. + - `Float = Float` - - `input: String` + - `UnionMember2 = bool` - The input for the custom tool call generated by the model. + - `UnionMember3 = Array[String | Float]` - - `name: String` + - `String = String` - The name of the custom tool being called. + - `Float = Float` - - `type: :custom_tool_call` + - `UnionMember1 = untyped` - The type of the custom tool call. Always `custom_tool_call`. + - `type: :and | :or` - - `:custom_tool_call` + Type of operation: `and` or `or`. - - `id: String` + - `:and` - The unique ID of the custom tool call in the OpenAI platform. + - `:or` - - `agent: Agent{ agent_name}` + - `max_num_results: Integer` - 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: RankingOptions{ hybrid_search, ranker, score_threshold}` - The canonical name of the agent that produced this item. + Ranking options for search. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - The execution context 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. - - `class Direct` + - `embedding_weight: Float` - - `type: :direct` + The weight of the embedding in the reciprocal ranking fusion. - - `:direct` + - `text_weight: Float` - - `class Program` + The weight of the text in the reciprocal ranking fusion. - - `caller_id: String` + - `ranker: :auto | :"default-2024-11-15"` - The call ID of the program item that produced this tool call. + The ranker to use for the file search. - - `type: :program` + - `:auto` - - `:program` + - `:"default-2024-11-15"` - - `namespace: String` + - `score_threshold: Float` - The namespace of the custom tool being called. + 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. - - `class CompactionTrigger` + - `class BetaComputerTool` - Compacts the current context. Must be the final input item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :compaction_trigger` + - `type: :computer` - The type of the item. Always `compaction_trigger`. + The type of the computer tool. Always `computer`. - - `:compaction_trigger` + - `:computer` - - `agent: Agent{ agent_name}` + - `class BetaComputerUsePreviewTool` - 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: Integer` - The canonical name of the agent that produced this item. + The height of the computer display. - - `class ItemReference` + - `display_width: Integer` - An internal identifier for an item to reference. + The width of the computer display. - - `id: String` + - `environment: :windows | :mac | :linux | 2 more` - The ID of the item to reference. + The type of computer environment to control. - - `agent: Agent{ 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` - - `type: :item_reference` + - `:browser` - The type of item to reference. Always `item_reference`. + - `type: :computer_use_preview` - - `:item_reference` + The type of the computer use tool. Always `computer_use_preview`. - - `class Program` + - `:computer_use_preview` - - `id: String` + - `class BetaWebSearchTool` - The unique ID of this program 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). - - `call_id: String` + - `type: :web_search | :web_search_2025_08_26` - The stable call ID of the program item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `code: String` + - `:web_search` - The JavaScript source executed by programmatic tool calling. + - `:web_search_2025_08_26` - - `fingerprint: String` + - `filters: Filters{ allowed_domains}` - Opaque program replay fingerprint that must be round-tripped. + Filters for the search. - - `type: :program` + - `allowed_domains: Array[String]` - The item type. Always `program`. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `:program` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `agent: Agent{ agent_name}` + - `search_context_size: :low | :medium | :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` - - `class ProgramOutput` + - `:high` - - `id: String` + - `user_location: UserLocation{ city, country, region, 2 more}` - The unique ID of this program output item. + The approximate location of the user. - - `call_id: String` + - `city: String` - The call ID of the program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `result: String` + - `country: String` - The result produced by the program item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: :completed | :incomplete` + - `region: String` - The terminal status of the program output. + Free text input for the region of the user, e.g. `California`. - - `:completed` + - `timezone: String` - - `:incomplete` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: :program_output` + - `type: :approximate` - The item type. Always `program_output`. + The type of location approximation. Always `approximate`. - - `:program_output` + - `:approximate` - - `agent: Agent{ agent_name}` + - `class Mcp` - The agent that produced this item. + 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_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. - - `metadata: Hash[Symbol, String]` + - `type: :mcp` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The type of the MCP tool. Always `mcp`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `:mcp` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `allowed_callers: Array[:direct | :programmatic]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The tool invocation context(s). - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `:direct` - 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. + - `:programmatic` - - `:"gpt-5.6-sol"` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `:"gpt-5.6-terra"` + List of allowed tool names or a filter object. - - `:"gpt-5.6-luna"` + - `McpAllowedTools = Array[String]` - - `:"gpt-5.4"` + A string array of allowed tool names - - `:"gpt-5.4-mini"` + - `class McpToolFilter` - - `:"gpt-5.4-nano"` + A filter object to specify which tools are allowed. - - `:"gpt-5.4-mini-2026-03-17"` + - `read_only: bool` - - `:"gpt-5.4-nano-2026-03-17"` + Indicates whether or not a tool modifies data or is read-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.3-chat-latest"` + - `tool_names: Array[String]` - - `:"gpt-5.2"` + List of allowed tool names. - - `:"gpt-5.2-2025-12-11"` + - `authorization: String` - - `:"gpt-5.2-chat-latest"` + 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.2-pro"` + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `:"gpt-5.2-pro-2025-12-11"` + 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.1"` + Currently supported `connector_id` values are: - - `:"gpt-5.1-2025-11-13"` + - 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.1-codex"` + - `:connector_dropbox` - - `:"gpt-5.1-mini"` + - `:connector_gmail` - - `:"gpt-5.1-chat-latest"` + - `:connector_googlecalendar` - - `:"gpt-5"` + - `:connector_googledrive` - - `:"gpt-5-mini"` + - `:connector_microsoftteams` - - `:"gpt-5-nano"` + - `:connector_outlookcalendar` - - `:"gpt-5-2025-08-07"` + - `:connector_outlookemail` - - `:"gpt-5-mini-2025-08-07"` + - `:connector_sharepoint` - - `:"gpt-5-nano-2025-08-07"` + - `defer_loading: bool` - - `:"gpt-5-chat-latest"` + Whether this MCP tool is deferred and discovered via tool search. - - `:"gpt-4.1"` + - `headers: Hash[Symbol, String]` - - `:"gpt-4.1-mini"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `:"gpt-4.1-nano"` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `:"gpt-4.1-2025-04-14"` + Specify which of the MCP server's tools require approval. - - `:"gpt-4.1-mini-2025-04-14"` + - `class McpToolApprovalFilter` - - `:"gpt-4.1-nano-2025-04-14"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `:"o4-mini"` + - `always: Always{ read_only, tool_names}` - - `:"o4-mini-2025-04-16"` + A filter object to specify which tools are allowed. - - `:o3` + - `read_only: bool` - - `:"o3-2025-04-16"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:"o3-mini"` + - `tool_names: Array[String]` - - `:"o3-mini-2025-01-31"` + List of allowed tool names. - - `:o1` + - `never: Never{ read_only, tool_names}` - - `:"o1-2024-12-17"` + A filter object to specify which tools are allowed. - - `:"o1-preview"` + - `read_only: bool` - - `:"o1-preview-2024-09-12"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:"o1-mini"` + - `tool_names: Array[String]` - - `:"o1-mini-2024-09-12"` + List of allowed tool names. - - `:"gpt-4o"` + - `McpToolApprovalSetting = :always | :never` - - `:"gpt-4o-2024-11-20"` + 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-2024-08-06"` + - `:always` - - `:"gpt-4o-2024-05-13"` + - `:never` - - `:"gpt-4o-audio-preview"` + - `server_description: String` - - `:"gpt-4o-audio-preview-2024-10-01"` + Optional description of the MCP server, used to provide more context. - - `:"gpt-4o-audio-preview-2024-12-17"` + - `server_url: String` - - `:"gpt-4o-audio-preview-2025-06-03"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:"gpt-4o-mini-audio-preview"` + - `tunnel_id: String` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `:"gpt-4o-search-preview"` + - `class CodeInterpreter` - - `:"gpt-4o-mini-search-preview"` + A tool that runs Python code to help generate a response to a prompt. - - `:"gpt-4o-search-preview-2025-03-11"` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + 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. - - `:"chatgpt-4o-latest"` + - `String = String` - - `:"codex-mini-latest"` + The container ID. - - `:"gpt-4o-mini"` + - `class CodeInterpreterToolAuto` - - `:"gpt-4o-mini-2024-07-18"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `:"gpt-4-turbo"` + - `type: :auto` - - `:"gpt-4-turbo-2024-04-09"` + Always `auto`. - - `:"gpt-4-0125-preview"` + - `:auto` - - `:"gpt-4-turbo-preview"` + - `file_ids: Array[String]` - - `:"gpt-4-1106-preview"` + An optional list of uploaded files to make available to your code. - - `:"gpt-4-vision-preview"` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:"gpt-4"` + The memory limit for the code interpreter container. - - `:"gpt-4-0314"` + - `:"1g"` - - `:"gpt-4-0613"` + - `:"4g"` - - `:"gpt-4-32k"` + - `:"16g"` - - `:"gpt-4-32k-0314"` + - `:"64g"` - - `:"gpt-4-32k-0613"` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:"gpt-3.5-turbo"` + Network access policy for the container. - - `:"gpt-3.5-turbo-16k"` + - `class BetaContainerNetworkPolicyDisabled` - - `:"gpt-3.5-turbo-0301"` + - `type: :disabled` - - `:"gpt-3.5-turbo-0613"` + Disable outbound network access. Always `disabled`. - - `:"gpt-3.5-turbo-1106"` + - `:disabled` - - `:"gpt-3.5-turbo-0125"` + - `class BetaContainerNetworkPolicyAllowlist` - - `:"gpt-3.5-turbo-16k-0613"` + - `allowed_domains: Array[String]` - - `:"o1-pro"` + A list of allowed domains when type is `allowlist`. - - `:"o1-pro-2025-03-19"` + - `type: :allowlist` - - `:"o3-pro"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `:"o3-pro-2025-06-10"` + - `:allowlist` - - `:"o3-deep-research"` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `:"o3-deep-research-2025-06-26"` + Optional domain-scoped secrets for allowlisted domains. - - `:"o4-mini-deep-research"` + - `domain: String` - - `:"o4-mini-deep-research-2025-06-26"` + The domain associated with the secret. - - `:"computer-use-preview"` + - `name: String` - - `:"computer-use-preview-2025-03-11"` + The name of the secret to inject for the domain. - - `:"gpt-5-codex"` + - `value: String` - - `:"gpt-5-pro"` + The secret value to inject for the domain. - - `:"gpt-5-pro-2025-10-06"` + - `type: :code_interpreter` - - `:"gpt-5.1-codex-max"` + The type of the code interpreter tool. Always `code_interpreter`. - - `String = String` + - `:code_interpreter` - - `object: :response` + - `allowed_callers: Array[:direct | :programmatic]` - The object type of this resource - always set to `response`. + The tool invocation context(s). - - `:response` + - `:direct` - - `output: Array[BetaResponseOutputItem]` + - `:programmatic` - An array of content items generated by the model. + - `class ProgrammaticToolCalling` - - 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. + - `type: :programmatic_tool_calling` - - `class BetaResponseOutputMessage` + The type of the tool. Always `programmatic_tool_calling`. - An output message from the model. + - `:programmatic_tool_calling` - - `class BetaResponseFileSearchToolCall` + - `class ImageGeneration` - 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 tool that generates images using the GPT image models. - - `class BetaResponseFunctionToolCall` + - `type: :image_generation` - 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 the image generation tool. Always `image_generation`. - - `class BetaResponseFunctionToolCallOutputItem` + - `:image_generation` - - `id: String` + - `action: :generate | :edit | :auto` - The unique ID of the function call tool output. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `call_id: String` + - `:generate` - The unique ID of the function tool call generated by the model. + - `:edit` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:auto` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `background: :transparent | :opaque | :auto` - - `String = 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. - A string of the output of the function 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. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - Text, image, or file output of the function call. + - `:transparent` - - `class BetaResponseInputText` + - `:opaque` - A text input to the model. + - `:auto` - - `class BetaResponseInputImage` + - `input_fidelity: :high | :low` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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`. - - `class BetaResponseInputFile` + - `:high` - A file input to the model. + - `:low` - - `status: :in_progress | :completed | :incomplete` + - `input_image_mask: InputImageMask{ file_id, image_url}` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `:in_progress` + - `file_id: String` - - `:completed` + File ID for the mask image. - - `:incomplete` + - `image_url: String` - - `type: :function_call_output` + Base64-encoded mask image. - The type of the function tool call output. Always `function_call_output`. + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:function_call_output` + The image generation model to use. Default: `gpt-image-1`. - - `agent: Agent{ agent_name}` + - `String = String` - The agent that produced this item. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. + - `:"gpt-image-1"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-image-1-mini"` - The execution context that produced this tool call. + - `:"gpt-image-2"` - - `class Direct` + - `:"gpt-image-2-2026-04-21"` - - `type: :direct` + - `:"gpt-image-1.5"` - The caller type. Always `direct`. + - `:"chatgpt-image-latest"` - - `:direct` + - `moderation: :auto | :low` - - `class Program` + Moderation level for the generated image. Default: `auto`. - - `caller_id: String` + - `:auto` - The call ID of the program item that produced this tool call. + - `:low` - - `type: :program` + - `output_compression: Integer` - The caller type. Always `program`. + Compression level for the output image. Default: 100. - - `:program` + - `output_format: :png | :webp | :jpeg` - - `created_by: String` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of the actor that created the item. + - `:png` - - `class AgentMessage` + - `:webp` - - `id: String` + - `:jpeg` - The unique ID of the agent message. + - `partial_images: Integer` - - `author: String` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The sending agent identity. + - `quality: :low | :medium | :high | :auto` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Encrypted content sent between agents. + - `:low` - - `class BetaResponseInputText` + - `:medium` - A text input to the model. + - `:high` - - `class BetaResponseOutputText` + - `:auto` - A text output from the model. + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `class 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`. - A text content. + - `String = String` - - `text: String` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `type: :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`. - - `:text` + - `:"1024x1024"` - - `class SummaryText` + - `:"1024x1536"` - A summary text from the model. + - `:"1536x1024"` - - `text: String` + - `:auto` - A summary of the reasoning output from the model so far. + - `class LocalShell` - - `type: :summary_text` + A tool that allows the model to execute shell commands in a local environment. - The type of the object. Always `summary_text`. + - `type: :local_shell` - - `:summary_text` + The type of the local shell tool. Always `local_shell`. - - `class ReasoningText` + - `:local_shell` - Reasoning text from the model. + - `class BetaFunctionShellTool` - - `text: String` + A tool that allows the model to execute shell commands. - The reasoning text from the model. + - `type: :shell` - - `type: :reasoning_text` + The type of the shell tool. Always `shell`. - The type of the reasoning text. Always `reasoning_text`. + - `:shell` - - `:reasoning_text` + - `allowed_callers: Array[:direct | :programmatic]` - - `class BetaResponseOutputRefusal` + The tool invocation context(s). - A refusal from the model. + - `:direct` - - `class BetaResponseInputImage` + - `:programmatic` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `class ComputerScreenshot` + - `class BetaContainerAuto` - A screenshot of a computer. + - `type: :container_auto` - - `detail: :low | :high | :auto | :original` + Automatically creates a container for this request - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:container_auto` - - `:low` + - `file_ids: Array[String]` - - `:high` + An optional list of uploaded files to make available to your code. - - `:auto` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:original` + The memory limit for the container. - - `file_id: String` + - `:"1g"` - The identifier of an uploaded file that contains the screenshot. + - `:"4g"` - - `image_url: String` + - `:"16g"` - The URL of the screenshot image. + - `:"64g"` - - `type: :computer_screenshot` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Network access policy for the container. - - `:computer_screenshot` + - `class BetaContainerNetworkPolicyDisabled` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class 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. + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `mode: :explicit` + An optional list of skills referenced by id or inline data. - The breakpoint mode. Always `explicit`. + - `class BetaSkillReference` - - `:explicit` + - `skill_id: String` - - `class BetaResponseInputFile` + The ID of the referenced skill. - A file input to the model. + - `type: :skill_reference` - - `class EncryptedContent` + References a skill created with the /v1/skills endpoint. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `:skill_reference` - - `encrypted_content: String` + - `version: String` - Opaque encrypted content. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: :encrypted_content` + - `class BetaInlineSkill` - The type of the input item. Always `encrypted_content`. + - `description: String` - - `:encrypted_content` + The description of the skill. - - `recipient: String` + - `name: String` - The destination agent identity. + The name of the skill. - - `type: :agent_message` + - `source: BetaInlineSkillSource` - The type of the item. Always `agent_message`. + Inline skill payload - - `:agent_message` + - `data: String` - - `agent: Agent{ 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"` - - `class MultiAgentCall` + - `type: :base64` - - `id: String` + The type of the inline skill source. Must be `base64`. - The unique ID of the multi-agent call item. + - `:base64` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :inline` - The multi-agent action to execute. + Defines an inline skill for this request. - - `:spawn_agent` + - `:inline` - - `:interrupt_agent` + - `class BetaLocalEnvironment` - - `:list_agents` + - `type: :local` - - `:send_message` + Use a local computer environment. - - `:followup_task` + - `:local` - - `:wait_agent` + - `skills: Array[BetaLocalSkill]` - - `arguments: String` + An optional list of skills. - The JSON string of arguments generated for the action. + - `description: String` - - `call_id: String` + The description of the skill. - The unique ID linking this call to its output. + - `name: String` - - `type: :multi_agent_call` + The name of the skill. - The type of the multi-agent call. Always `multi_agent_call`. + - `path: String` - - `:multi_agent_call` + The path to the directory containing the skill. - - `agent: Agent{ agent_name}` + - `class BetaContainerReference` - The agent that produced this item. + - `container_id: String` - - `agent_name: String` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: :container_reference` - - `class MultiAgentCallOutput` + References a container created with the /v1/containers endpoint - - `id: String` + - `:container_reference` - The unique ID of the multi-agent call output item. + - `class BetaCustomTool` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 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 produced this result. + - `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: Array[:direct | :programmatic]` - - `:wait_agent` + The tool invocation context(s). - - `call_id: String` + - `:direct` - The unique ID of the multi-agent call. + - `:programmatic` - - `output: Array[BetaResponseOutputText]` + - `defer_loading: bool` - Text output returned by the multi-agent action. + Whether this tool should be deferred and discovered via tool search. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `description: String` - The annotations of the text output. + Optional description of the custom tool, used to provide more context. - - `text: String` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - The text output from the model. + The input format for the custom tool. Default is unconstrained text. - - `type: :output_text` + - `class Text` - The type of the output text. Always `output_text`. + Unconstrained free-form text. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `type: :text` - - `type: :multi_agent_call_output` + Unconstrained text format. Always `text`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `:text` - - `:multi_agent_call_output` + - `class Grammar` - - `agent: Agent{ 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 | :regex` - - `class BetaResponseFunctionWebSearch` + The syntax of the grammar definition. One of `lark` or `regex`. - 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. + - `:lark` - - `class BetaResponseComputerToolCall` + - `:regex` - 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: :grammar` - - `class BetaResponseComputerToolCallOutputItem` + Grammar format. Always `grammar`. - - `id: String` + - `:grammar` - The unique ID of the computer call tool output. + - `class BetaNamespaceTool` - - `call_id: String` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call that produced the output. + - `description: String` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A description of the namespace shown to the model. - A computer screenshot image used with the computer use tool. + - `name: String` - - `status: :completed | :incomplete | :failed | :in_progress` + The namespace name used in tool calls (for example, `crm`). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `:completed` + The function/custom tools available inside this namespace. - - `:incomplete` + - `class Function` - - `:failed` + - `name: String` - - `:in_progress` + - `type: :function` - - `type: :computer_call_output` + - `:function` - The type of the computer tool call output. Always `computer_call_output`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:computer_call_output` + The tool invocation context(s). - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `:direct` - The safety checks reported by the API that have been acknowledged by the - developer. + - `:programmatic` - - `id: String` + - `defer_loading: bool` - The ID of the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `code: String` + - `description: String` - The type of the pending safety check. + - `output_schema: Hash[Symbol, untyped]` - - `message: String` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Details about the pending safety check. + - `parameters: untyped` - - `agent: Agent{ agent_name}` + - `strict: bool` - The agent that produced this item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `agent_name: String` + - `class BetaCustomTool` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `created_by: String` + - `type: :namespace` - The identifier of the actor that created the item. + The type of the tool. Always `namespace`. - - `class BetaResponseReasoningItem` + - `:namespace` - 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). + - `class BetaToolSearchTool` - - `class Program` + 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: String` - - `code: String` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `execution: :server | :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: untyped` - - `:program` + Parameter schema for a client-executed tool search tool. - - `agent: Agent{ agent_name}` + - `class BetaWebSearchPreviewTool` - 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 | :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`. - - `class ProgramOutput` + - `:web_search_preview` - - `id: String` + - `:web_search_preview_2025_03_11` - The unique ID of the program output item. + - `search_content_types: Array[:text | :image]` - - `call_id: String` + - `:text` - The call ID of the program item. + - `:image` - - `result: String` + - `search_context_size: :low | :medium | :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 | :incomplete` + - `:low` - The terminal status of the program output item. + - `:medium` - - `:completed` + - `:high` - - `:incomplete` + - `user_location: UserLocation{ 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: Agent{ agent_name}` + - `:approximate` - The agent that produced this item. + - `city: 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: String` - - `class BetaResponseToolSearchCall` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `id: String` + - `region: String` - The unique ID of the tool search call item. + Free text input for the region of the user, e.g. `California`. - - `arguments: untyped` + - `timezone: 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` + - `class BetaApplyPatchTool` - 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 | :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: Array[:direct | :programmatic]` - - `status: :in_progress | :completed | :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: String` - - `:tool_search_call` + The unique ID of this tool search output. - `agent: Agent{ agent_name}` @@ -30064,16 +40390,6 @@ Get a model response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem` - - - `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. @@ -30088,7 +40404,7 @@ Get a model response - `status: :in_progress | :completed | :incomplete` - The status of the tool search output item that was recorded. + The status of the tool search output. - `:in_progress` @@ -30096,9 +40412,17 @@ Get a model response - `:incomplete` + - `class AdditionalTools` + + - `role: :developer` + + The role that provided the additional tools. Only `developer` is supported. + + - `:developer` + - `tools: Array[BetaTool]` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `class BetaFunctionTool` @@ -30164,11 +40488,15 @@ Get a model response Allows the assistant to create, delete, or update files using unified diffs. - - `type: :tool_search_output` + - `type: :additional_tools` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `:tool_search_output` + - `:additional_tools` + + - `id: String` + + The unique ID of this additional tools item. - `agent: Agent{ agent_name}` @@ -30178,109 +40506,130 @@ Get a model response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningItem` - - `class AdditionalTools` + 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 ID of the additional tools item. + The unique identifier of the reasoning content. - - `role: :unknown | :user | :assistant | 5 more` + - `summary: Array[Summary{ text, type}]` - The role that provided the additional tools. + Reasoning summary content. - - `:unknown` + - `text: String` - - `:user` + A summary of the reasoning output from the model so far. - - `:assistant` + - `type: :summary_text` - - `:system` + The type of the object. Always `summary_text`. - - `:critic` + - `:summary_text` - - `:discriminator` + - `type: :reasoning` - - `:developer` + The type of the object. Always `reasoning`. - - `:tool` + - `:reasoning` - - `tools: Array[BetaTool]` + - `agent: Agent{ agent_name}` - The additional tool definitions made available at this item. + The agent that produced this item. - - `class BetaFunctionTool` + - `agent_name: String` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool` + - `content: Array[Content{ text, 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). + Reasoning text content. - - `class BetaComputerTool` + - `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 reasoning text from the model. - - `class BetaComputerUsePreviewTool` + - `type: :reasoning_text` - 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 reasoning text. Always `reasoning_text`. - - `class BetaWebSearchTool` + - `: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). + - `encrypted_content: String` - - `class Mcp` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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). + - `status: :in_progress | :completed | :incomplete` - - `class CodeInterpreter` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool that runs Python code to help generate a response to a prompt. + - `:in_progress` - - `class ProgrammaticToolCalling` + - `:completed` - - `class ImageGeneration` + - `:incomplete` - A tool that generates images using the GPT image models. + - `class BetaResponseCompactionItemParam` - - `class LocalShell` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A tool that allows the model to execute shell commands in a local environment. + - `encrypted_content: String` - - `class BetaFunctionShellTool` + The encrypted content of the compaction summary. - A tool that allows the model to execute shell commands. + - `type: :compaction` - - `class BetaCustomTool` + The type of the item. Always `compaction`. - 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) + - `:compaction` - - `class BetaNamespaceTool` + - `id: String` - Groups function/custom tools under a shared namespace. + The ID of the compaction item. - - `class BetaToolSearchTool` + - `agent: Agent{ agent_name}` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `class BetaWebSearchPreviewTool` + - `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. - - `class BetaApplyPatchTool` + - `class ImageGenerationCall` - Allows the assistant to create, delete, or update files using unified diffs. + An image generation request made by the model. - - `type: :additional_tools` + - `id: String` - The type of the item. Always `additional_tools`. + The unique ID of the image generation call. - - `:additional_tools` + - `result: String` + + The generated image encoded in base64. + + - `status: :in_progress | :completed | :generating | :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: Agent{ agent_name}` @@ -30290,65 +40639,74 @@ Get a model response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` + - `class BetaResponseCodeInterpreterToolCall` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A tool call to run code. - `id: String` - The unique ID of the compaction item. + The unique ID of the code interpreter tool call. - - `encrypted_content: String` + - `code: String` - The encrypted content that was produced by compaction. + The code to run, or null if not available. - - `type: :compaction` + - `container_id: String` - The type of the item. Always `compaction`. + The ID of the container used to run the code. - - `:compaction` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `agent: Agent{ agent_name}` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The agent that produced this item. + - `class Logs` - - `agent_name: String` + The logs output from the code interpreter. - The canonical name of the agent that produced this item. + - `logs: String` - - `created_by: String` + The logs output from the code interpreter. - The identifier of the actor that created the item. + - `type: :logs` - - `class ImageGenerationCall` + The type of the output. Always `logs`. - An image generation request made by the model. + - `:logs` - - `id: String` + - `class Image` - The unique ID of the image generation call. + The image output from the code interpreter. - - `result: String` + - `type: :image` - The generated image encoded in base64. + The type of the output. Always `image`. - - `status: :in_progress | :completed | :generating | :failed` + - `:image` - The status of the image generation call. + - `url: String` + + The URL of the image output from the code interpreter. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `:in_progress` - `:completed` - - `:generating` + - `:incomplete` + + - `:interpreting` - `:failed` - - `type: :image_generation_call` + - `type: :code_interpreter_call` - The type of the image generation call. Always `image_generation_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `:image_generation_call` + - `:code_interpreter_call` - `agent: Agent{ agent_name}` @@ -30358,10 +40716,6 @@ Get a model response The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` - - A tool call to run code. - - `class LocalShellCall` A tool call to run a command on the local shell. @@ -30464,13 +40818,9 @@ Get a model response - `:incomplete` - - `class BetaResponseFunctionShellToolCall` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: String` + - `class ShellCall` - 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: Action{ commands, max_output_length, timeout_ms}` @@ -30478,60 +40828,30 @@ Get a model response - `commands: Array[String]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Integer` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Integer` - Optional timeout in milliseconds for the commands. + 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 | BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class BetaResponseContainerReference` - - Represents a container created with /v1/containers. - - - `container_id: String` - - - `type: :container_reference` - - The environment type. Always `container_reference`. - - - `:container_reference` - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -30548,6 +40868,8 @@ Get a model response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -30558,35 +40880,43 @@ Get a model response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `environment: BetaLocalEnvironment | BetaContainerReference` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput` + - `class BetaLocalEnvironment` - The output of a shell tool call that was emitted. + - `class BetaContainerReference` - - `id: String` + - `status: :in_progress | :completed | :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: Integer` + - `:incomplete` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput` - - `output: Array[Output{ 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[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Timeout{ type} | Exit{ 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. - `class Timeout` @@ -30604,7 +40934,7 @@ Get a model response - `exit_code: Integer` - Exit code from the shell process. + The exit code returned by the shell process. - `type: :exit` @@ -30614,32 +40944,22 @@ Get a model 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: String` - - The identifier of the actor that created the item. - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -30656,6 +40976,8 @@ Get a model response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -30666,19 +40988,27 @@ Get a model response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `max_output_length: Integer` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall` + - `status: :in_progress | :completed | :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` + + - `class ApplyPatchCall` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: String` @@ -30686,55 +41016,55 @@ Get a model response - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ 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. - `class CreateFile` - 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` - `class DeleteFile` - 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` - `class UpdateFile` - 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` @@ -30752,6 +41082,10 @@ Get a model response - `:apply_patch_call` + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -30768,6 +41102,8 @@ Get a model response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -30778,19 +41114,13 @@ Get a model response - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `:program` - - `id: String` + - `class ApplyPatchCallOutput` - 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` @@ -30810,6 +41140,10 @@ Get a model response - `:apply_patch_call_output` + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -30826,6 +41160,8 @@ Get a model response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -30836,15 +41172,131 @@ Get a model response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `output: String` - The ID of the entity that created this tool call output. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `output: String` + - `class McpListTools` - Optional textual output returned by the apply patch tool. + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. - `class McpCall` @@ -30907,43 +41359,148 @@ Get a model response - `:failed` - - `class McpListTools` + - `class BetaResponseCustomToolCallOutput` - A list of tools available on an MCP server. + 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + 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: String` - The unique ID of the list. + The unique ID of the custom tool call output in the OpenAI platform. - - `server_label: String` + - `agent: Agent{ agent_name}` - The label of the MCP server. + The agent that produced this item. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `agent_name: String` - The tools available on the server. + The canonical name of the agent that produced this item. - - `input_schema: untyped` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The JSON schema describing the tool's input. + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + 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 tool. + The name of the custom tool being called. - - `annotations: untyped` + - `type: :custom_tool_call` - Additional annotations about the tool. + The type of the custom tool call. Always `custom_tool_call`. - - `description: String` + - `:custom_tool_call` - The description of the tool. + - `id: String` - - `type: :mcp_list_tools` + The unique ID of the custom tool call in the OpenAI platform. - The type of the item. Always `mcp_list_tools`. + - `agent: Agent{ agent_name}` - - `:mcp_list_tools` + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` - `agent: Agent{ agent_name}` @@ -30953,35 +41510,51 @@ Get a model response The canonical name of the agent that produced this item. - - `error: String` + - `class ItemReference` - Error message if the server could not list tools. + An internal identifier for an item to reference. - - `class McpApprovalRequest` + - `id: String` - A request for human approval of a tool invocation. + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` - `id: String` - The unique ID of the approval request. + The unique ID of this program item. - - `arguments: String` + - `call_id: String` - A JSON string of arguments for the tool. + The stable call ID of the program item. - - `name: String` + - `code: String` - The name of the tool to run. + The JavaScript source executed by programmatic tool calling. - - `server_label: String` + - `fingerprint: String` - The label of the MCP server making the request. + Opaque program replay fingerprint that must be round-tripped. - - `type: :mcp_approval_request` + - `type: :program` - The type of the item. Always `mcp_approval_request`. + The item type. Always `program`. - - `:mcp_approval_request` + - `:program` - `agent: Agent{ agent_name}` @@ -30991,51 +41564,322 @@ Get a model response The canonical name of the agent that produced this item. - - `class McpApprovalResponse` + - `class ProgramOutput` - A response to an MCP approval request. + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. + + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 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"` + + - `:"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 = String` + + - `object: :response` + + The object type of this resource - always set to `response`. + + - `:response` + + - `output: Array[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. + + - `class BetaResponseOutputMessage` + + An output message from the model. - - `id: String` + - `class BetaResponseFileSearchToolCall` - The unique ID of the approval 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. - - `approval_request_id: String` + - `class BetaResponseFunctionToolCall` - The ID of the approval request being answered. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `approve: bool` + - `class BetaResponseFunctionToolCallOutputItem` - Whether the request was approved. + - `id: String` - - `type: :mcp_approval_response` + The unique ID of the function call tool output. - The type of the item. Always `mcp_approval_response`. + - `call_id: String` - - `:mcp_approval_response` + The unique ID of the function tool call generated by the model. - - `agent: Agent{ agent_name}` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The agent that produced this item. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `agent_name: String` + - `String = String` - The canonical name of the agent that produced this item. + A string of the output of the function call. - - `reason: String` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - Optional reason for the decision. + Text, image, or file output of the function call. - - `class BetaResponseCustomToolCall` + - `class BetaResponseInputText` - A call to a custom tool created by the model. + A text input to the model. - - `class BetaResponseCustomToolCallOutputItem` + - `class BetaResponseInputImage` - The output of a custom tool call from your code, being sent back to the model. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: String` + - `class BetaResponseInputFile` - The unique ID of the custom tool call output item. + A file input to the model. - `status: :in_progress | :completed | :incomplete` @@ -31048,1500 +41892,1232 @@ Get a model response - `:incomplete` - - `created_by: String` - - The identifier of the actor that created the item. - - - `parallel_tool_calls: bool` - - Whether to allow the model to run tool calls in parallel. - - - `temperature: Float` - - 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 | BetaToolChoiceAllowed | BetaToolChoiceTypes | 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 | :auto | :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. + - `type: :function_call_output` - `auto` means the model can pick between generating a message or calling one or - more tools. + The type of the function tool call output. Always `function_call_output`. - `required` means the model must call one or more tools. + - `:function_call_output` - - `:none` + - `agent: Agent{ agent_name}` - - `:auto` + The agent that produced this item. - - `:required` + - `agent_name: String` - - `class BetaToolChoiceAllowed` + The canonical name of the agent that produced this item. - Constrains the tools available to the model to a pre-defined set. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `mode: :auto | :required` + The execution context that produced this tool call. - Constrains the tools available to the model to a pre-defined set. + - `class Direct` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `type: :direct` - `required` requires the model to call one or more of the allowed tools. + The caller type. Always `direct`. - - `:auto` + - `:direct` - - `:required` + - `class Program` - - `tools: Array[Hash[Symbol, untyped]]` + - `caller_id: String` - A list of tool definitions that the model should be allowed to call. + The call ID of the program item that produced this tool call. - For the Responses API, the list of tool definitions might look like: + - `type: :program` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The caller type. Always `program`. - - `type: :allowed_tools` + - `:program` - Allowed tool configuration type. Always `allowed_tools`. + - `created_by: String` - - `:allowed_tools` + The identifier of the actor that created the item. - - `class BetaToolChoiceTypes` + - `class AgentMessage` - 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). + - `id: String` - - `type: :file_search | :web_search_preview | :computer | 5 more` + The unique ID of the agent message. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `author: String` - Allowed values are: + The sending agent identity. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `:file_search` + Encrypted content sent between agents. - - `:web_search_preview` + - `class BetaResponseInputText` - - `:computer` + A text input to the model. - - `:computer_use_preview` + - `class BetaResponseOutputText` - - `:computer_use` + A text output from the model. - - `:web_search_preview_2025_03_11` + - `class Text` - - `:image_generation` + A text content. - - `:code_interpreter` + - `text: String` - - `class BetaToolChoiceFunction` + - `type: :text` - Use this option to force the model to call a specific function. + - `:text` - - `name: String` + - `class SummaryText` - The name of the function to call. + A summary text from the model. - - `type: :function` + - `text: String` - For function calling, the type is always `function`. + A summary of the reasoning output from the model so far. - - `:function` + - `type: :summary_text` - - `class BetaToolChoiceMcp` + The type of the object. Always `summary_text`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `:summary_text` - - `server_label: String` + - `class ReasoningText` - The label of the MCP server to use. + Reasoning text from the model. - - `type: :mcp` + - `text: String` - For MCP tools, the type is always `mcp`. + The reasoning text from the model. - - `:mcp` + - `type: :reasoning_text` - - `name: String` + The type of the reasoning text. Always `reasoning_text`. - The name of the tool to call on the server. + - `:reasoning_text` - - `class BetaToolChoiceCustom` + - `class BetaResponseOutputRefusal` - Use this option to force the model to call a specific custom tool. + A refusal from the model. - - `name: String` + - `class BetaResponseInputImage` - The name of the custom tool to call. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `type: :custom` + - `class ComputerScreenshot` - For custom tool calling, the type is always `custom`. + A screenshot of a computer. - - `:custom` + - `detail: :low | :high | :auto | :original` - - `class BetaSpecificProgrammaticToolCallingParam` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :programmatic_tool_calling` + - `:low` - The tool to call. Always `programmatic_tool_calling`. + - `:high` - - `:programmatic_tool_calling` + - `:auto` - - `class BetaToolChoiceApplyPatch` + - `:original` - Forces the model to call the apply_patch tool when executing a tool call. + - `file_id: String` - - `type: :apply_patch` + The identifier of an uploaded file that contains the screenshot. - The tool to call. Always `apply_patch`. + - `image_url: String` - - `:apply_patch` + The URL of the screenshot image. - - `class BetaToolChoiceShell` + - `type: :computer_screenshot` - Forces the model to call the shell tool when a tool call is required. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `type: :shell` + - `:computer_screenshot` - The tool to call. Always `shell`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:shell` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `tools: Array[BetaTool]` + - `mode: :explicit` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The breakpoint mode. Always `explicit`. - We support the following categories of tools: + - `:explicit` - - **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. + - `class BetaResponseInputFile` - - `class BetaFunctionTool` + A file input to the model. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class EncryptedContent` - - `class BetaFileSearchTool` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - 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). + - `encrypted_content: String` - - `class BetaComputerTool` + Opaque encrypted content. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :encrypted_content` - - `class BetaComputerUsePreviewTool` + The type of the input item. Always `encrypted_content`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:encrypted_content` - - `class BetaWebSearchTool` + - `recipient: 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 destination agent identity. - - `class Mcp` + - `type: :agent_message` - 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 type of the item. Always `agent_message`. - - `class CodeInterpreter` + - `:agent_message` - A tool that runs Python code to help generate a response to a prompt. + - `agent: Agent{ agent_name}` - - `class ProgrammaticToolCalling` + The agent that produced this item. - - `class ImageGeneration` + - `agent_name: String` - A tool that generates images using the GPT image models. + The canonical name of the agent that produced this item. - - `class LocalShell` + - `class MultiAgentCall` - A tool that allows the model to execute shell commands in a local environment. + - `id: String` - - `class BetaFunctionShellTool` + The unique ID of the multi-agent call item. - A tool that allows the model to execute shell commands. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `class BetaCustomTool` + The multi-agent action to execute. - 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) + - `:spawn_agent` - - `class BetaNamespaceTool` + - `:interrupt_agent` - Groups function/custom tools under a shared namespace. + - `:list_agents` - - `class BetaToolSearchTool` + - `:send_message` - Hosted or BYOT tool search configuration for deferred tools. + - `:followup_task` - - `class BetaWebSearchPreviewTool` + - `:wait_agent` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `arguments: String` - - `class BetaApplyPatchTool` + The JSON string of arguments generated for the action. - Allows the assistant to create, delete, or update files using unified diffs. + - `call_id: String` - - `top_p: Float` + The unique ID linking this call to its 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. + - `type: :multi_agent_call` - We generally recommend altering this or `temperature` but not both. + The type of the multi-agent call. Always `multi_agent_call`. - - `background: bool` + - `:multi_agent_call` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `agent: Agent{ agent_name}` - - `completed_at: Float` + The agent that produced this item. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `agent_name: String` - - `conversation: Conversation{ id}` + The canonical name of 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. + - `class MultiAgentCallOutput` - `id: String` - The unique ID of the conversation that this response was associated with. - - - `max_output_tokens: Integer` - - 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: Integer` - - 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: Moderation{ input, output}` + The unique ID of the multi-agent call output item. - Moderation results for the response input and output, if moderated completions were requested. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + The multi-agent action that produced this result. - Moderation for the response input. + - `:spawn_agent` - - `class ModerationResult` + - `:interrupt_agent` - A moderation result produced for the response input or output. + - `:list_agents` - - `categories: Hash[Symbol, bool]` + - `:send_message` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `:followup_task` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `:wait_agent` - Which modalities of input are reflected by the score for each category. + - `call_id: String` - - `:text` + The unique ID of the multi-agent call. - - `:image` + - `output: Array[BetaResponseOutputText]` - - `category_scores: Hash[Symbol, Float]` + Text output returned by the multi-agent action. - A dictionary of moderation categories to scores. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `flagged: bool` + The annotations of the text output. - A boolean indicating whether the content was flagged by any category. + - `text: String` - - `model: String` + The text output from the model. - The moderation model that produced this result. + - `type: :output_text` - - `type: :moderation_result` + The type of the output text. Always `output_text`. - The object type, which was always `moderation_result` for successful moderation results. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `:moderation_result` + - `type: :multi_agent_call_output` - - `class Error` + The type of the multi-agent result. Always `multi_agent_call_output`. - An error produced while attempting moderation for the response input or output. + - `:multi_agent_call_output` - - `code: String` + - `agent: Agent{ 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` + - `class BetaResponseFunctionWebSearch` - The object type, which was always `error` for moderation failures. + 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. - - `:error` + - `class BetaResponseComputerToolCall` - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, 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. - Moderation for the response output. + - `class BetaResponseComputerToolCallOutputItem` - - `class ModerationResult` + - `id: String` - A moderation result produced for the response input or output. + The unique ID of the computer call tool output. - - `categories: Hash[Symbol, bool]` + - `call_id: String` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The ID of the computer tool call that produced the output. - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Which modalities of input are reflected by the score for each category. + A computer screenshot image used with the computer use tool. - - `:text` + - `status: :completed | :incomplete | :failed | :in_progress` - - `:image` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `category_scores: Hash[Symbol, Float]` + - `:completed` - A dictionary of moderation categories to scores. + - `:incomplete` - - `flagged: bool` + - `:failed` - A boolean indicating whether the content was flagged by any category. + - `:in_progress` - - `model: String` + - `type: :computer_call_output` - The moderation model that produced this result. + The type of the computer tool call output. Always `computer_call_output`. - - `type: :moderation_result` + - `:computer_call_output` - The object type, which was always `moderation_result` for successful moderation results. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:moderation_result` + The safety checks reported by the API that have been acknowledged by the + developer. - - `class Error` + - `id: String` - An error produced while attempting moderation for the response input or output. + The ID of the pending safety check. - `code: String` - The error code. + The type of the pending safety check. - `message: String` - The error message. + Details about the pending safety check. - - `type: :error` + - `agent: Agent{ agent_name}` - The object type, which was always `error` for moderation failures. + The agent that produced this item. - - `:error` + - `agent_name: String` - - `previous_response_id: 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`. + - `created_by: String` - - `prompt: BetaResponsePrompt` + The identifier of the actor that created the item. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `class BetaResponseReasoningItem` - - `id: 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). - The unique identifier of the prompt template to use. + - `class Program` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `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 unique ID of the program item. - - `String = String` + - `call_id: String` - - `class BetaResponseInputText` + The stable call ID of the program item. - A text input to the model. + - `code: String` - - `class BetaResponseInputImage` + The JavaScript source executed by programmatic tool calling. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `fingerprint: String` - - `class BetaResponseInputFile` + Opaque program replay fingerprint that must be round-tripped. - A file input to the model. + - `type: :program` - - `version: String` + The type of the item. Always `program`. - Optional version of the prompt template. + - `:program` - - `prompt_cache_key: String` + - `agent: Agent{ agent_name}` - 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 agent that produced this item. - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `agent_name: String` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The canonical name of the agent that produced this item. - - `mode: :implicit | :explicit` + - `class ProgramOutput` - Whether implicit prompt-cache breakpoints were enabled. + - `id: String` - - `:implicit` + The unique ID of the program output item. - - `:explicit` + - `call_id: String` - - `ttl: :"30m"` + The call ID of the program item. - The minimum lifetime applied to each cache breakpoint. + - `result: String` - - `:"30m"` + The result produced by the program item. - - `prompt_cache_retention: :in_memory | :"24h"` + - `status: :completed | :incomplete` - Deprecated. Use `prompt_cache_options.ttl` instead. + The terminal status of the program output item. - 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. + - `:completed` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `:incomplete` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: :program_output` - - `:in_memory` + The type of the item. Always `program_output`. - - `:"24h"` + - `:program_output` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `agent: Agent{ agent_name}` - **gpt-5 and o-series models only** + The agent that produced this item. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `agent_name: String` - - `context: :auto | :current_turn | :all_turns` + The canonical name of the agent that produced this item. - 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. + - `class BetaResponseToolSearchCall` - - `:auto` + - `id: String` - - `:current_turn` + The unique ID of the tool search call item. - - `:all_turns` + - `arguments: untyped` - - `effort: :none | :minimal | :low | 4 more` + Arguments used for the tool search 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. + - `call_id: String` - - `:none` + The unique ID of the tool search call generated by the model. - - `:minimal` + - `execution: :server | :client` - - `:low` + Whether tool search was executed by the server or by the client. - - `:medium` + - `:server` - - `:high` + - `:client` - - `:xhigh` + - `status: :in_progress | :completed | :incomplete` - - `:max` + The status of the tool search call item that was recorded. - - `generate_summary: :auto | :concise | :detailed` + - `:in_progress` - **Deprecated:** use `summary` instead. + - `: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` - - `:auto` + - `type: :tool_search_call` - - `:concise` + The type of the item. Always `tool_search_call`. - - `:detailed` + - `:tool_search_call` - - `mode: String | :standard | :pro` + - `agent: Agent{ 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` - - `String = String` + The canonical name of the agent that produced this item. - - `Mode = :standard | :pro` + - `created_by: String` - Controls the reasoning execution mode for the request. + The identifier of the actor that created the item. - When returned on a response, this is the effective execution mode. + - `class BetaResponseToolSearchOutputItem` - - `:standard` + - `id: String` - - `:pro` + The unique ID of the tool search output item. - - `summary: :auto | :concise | :detailed` + - `call_id: String` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The unique ID of the tool search call generated by the model. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `execution: :server | :client` - - `:auto` + Whether tool search was executed by the server or by the client. - - `:concise` + - `:server` - - `:detailed` + - `:client` - - `safety_identifier: String` + - `status: :in_progress | :completed | :incomplete` - 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 status of the tool search output item that was recorded. - - `service_tier: :auto | :default | :flex | 2 more` + - `:in_progress` - Specifies the processing type used for serving the request. + - `:completed` - - 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'. + - `:incomplete` - 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. + - `tools: Array[BetaTool]` - - `:auto` + The loaded tool definitions returned by tool search. - - `:default` + - `class BetaFunctionTool` - - `:flex` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `:scale` + - `class BetaFileSearchTool` - - `:priority` + 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: BetaResponseStatus` + - `class BetaComputerTool` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:completed` + - `class BetaComputerUsePreviewTool` - - `: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` + - `class BetaWebSearchTool` - - `:cancelled` + 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). - - `:queued` + - `class Mcp` - - `: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). - - `text: BetaResponseTextConfig` + - `class CodeInterpreter` - 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](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `class ProgrammaticToolCalling` - - `format_: BetaResponseFormatTextConfig` + - `class ImageGeneration` - An object specifying the format that the model must output. + A tool that generates images using the GPT image models. - 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). + - `class LocalShell` - The default format is `{ "type": "text" }` with no additional options. + A tool that allows the model to execute shell commands in a local environment. - **Not recommended for gpt-4o and newer models:** + - `class BetaFunctionShellTool` - 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 allows the model to execute shell commands. - - `class Text` + - `class BetaCustomTool` - Default response format. Used to generate text responses. + 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: :text` + - `class BetaNamespaceTool` - The type of response format being defined. Always `text`. + Groups function/custom tools under a shared namespace. - - `:text` + - `class BetaToolSearchTool` - - `class BetaResponseFormatTextJSONSchemaConfig` + Hosted or BYOT tool search configuration for deferred tools. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `class BetaWebSearchPreviewTool` - - `name: String` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `class BetaApplyPatchTool` - - `schema: Hash[Symbol, untyped]` + Allows the assistant to create, delete, or update files using unified diffs. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: :tool_search_output` - - `type: :json_schema` + The type of the item. Always `tool_search_output`. - The type of response format being defined. Always `json_schema`. + - `:tool_search_output` - - `:json_schema` + - `agent: Agent{ agent_name}` - - `description: String` + The agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent_name: String` - - `strict: bool` + 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). + - `created_by: String` - - `class JSONObject` + The identifier of the actor that created the 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. + - `class AdditionalTools` - - `type: :json_object` + - `id: String` - The type of response format being defined. Always `json_object`. + The unique ID of the additional tools item. - - `:json_object` + - `role: :unknown | :user | :assistant | 5 more` - - `verbosity: :low | :medium | :high` + The role that provided the additional tools. - 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`. + - `:unknown` - - `:low` + - `:user` - - `:medium` + - `:assistant` - - `:high` + - `:system` - - `top_logprobs: Integer` + - `:critic` - 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. + - `:discriminator` - - `truncation: :auto | :disabled` + - `:developer` - The truncation strategy to use for the model response. + - `: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. + - `tools: Array[BetaTool]` - - `:auto` + The additional tool definitions made available at this item. - - `:disabled` + - `class BetaFunctionTool` - - `usage: BetaResponseUsage` + 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). - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `class BetaFileSearchTool` - - `input_tokens: Integer` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The number of input tokens. + - `class BetaComputerTool` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A detailed breakdown of the input tokens. + - `class BetaComputerUsePreviewTool` - - `cache_write_tokens: Integer` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The number of input tokens that were written to the cache. + - `class BetaWebSearchTool` - - `cached_tokens: Integer` + 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 number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `class Mcp` - - `output_tokens: Integer` + 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 number of output tokens. + - `class CodeInterpreter` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + A tool that runs Python code to help generate a response to a prompt. - A detailed breakdown of the output tokens. + - `class ProgrammaticToolCalling` - - `reasoning_tokens: Integer` + - `class ImageGeneration` - The number of reasoning tokens. + A tool that generates images using the GPT image models. - - `total_tokens: Integer` + - `class LocalShell` - The total number of tokens used. + A tool that allows the model to execute shell commands in a local environment. - - `user: String` + - `class BetaFunctionShellTool` - 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). + A tool that allows the model to execute shell commands. -### Example + - `class BetaCustomTool` -```ruby -require "openai" + 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) -openai = OpenAI::Client.new(api_key: "My API Key") + - `class BetaNamespaceTool` -beta_response = openai.beta.responses.retrieve("resp_677efb5139a88190b512bc3fef8e535d") + Groups function/custom tools under a shared namespace. -puts(beta_response) -``` + - `class BetaToolSearchTool` -#### Response + Hosted or BYOT tool search configuration for deferred tools. -```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" -} -``` + - `class BetaWebSearchPreviewTool` -## Delete a model response + 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.responses.delete(response_id, **kwargs) -> void` + - `class BetaApplyPatchTool` -**delete** `/responses/{response_id}?beta=true` + Allows the assistant to create, delete, or update files using unified diffs. -Delete a model response + - `type: :additional_tools` -### Parameters + The type of the item. Always `additional_tools`. -- `response_id: String` + - `:additional_tools` -- `betas: Array[:"responses_multi_agent=v1"]` + - `agent: Agent{ agent_name}` - - `:"responses_multi_agent=v1"` + The agent that produced this item. -### Example + - `agent_name: String` -```ruby -require "openai" + The canonical name of the agent that produced this item. -openai = OpenAI::Client.new(api_key: "My API Key") + - `class BetaResponseCompactionItem` -result = openai.beta.responses.delete("resp_677efb5139a88190b512bc3fef8e535d") + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). -puts(result) -``` + - `id: String` -## Cancel a response + The unique ID of the compaction item. -`beta.responses.cancel(response_id, **kwargs) -> BetaResponse` + - `encrypted_content: String` -**post** `/responses/{response_id}/cancel?beta=true` + The encrypted content that was produced by compaction. -Cancel a response + - `type: :compaction` -### Parameters + The type of the item. Always `compaction`. -- `response_id: String` + - `:compaction` -- `betas: Array[:"responses_multi_agent=v1"]` + - `agent: Agent{ agent_name}` - - `:"responses_multi_agent=v1"` + The agent that produced this item. -### Returns + - `agent_name: String` -- `class BetaResponse` + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class ImageGenerationCall` + + An image generation request made by the model. - `id: String` - Unique identifier for this Response. + The unique ID of the image generation call. - - `created_at: Float` + - `result: String` - Unix timestamp (in seconds) of when this Response was created. + The generated image encoded in base64. - - `error: BetaResponseError` + - `status: :in_progress | :completed | :generating | :failed` - An error object returned when the model fails to generate a Response. + The status of the image generation call. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `:in_progress` - The error code for the response. + - `:completed` - - `:server_error` + - `:generating` - - `:rate_limit_exceeded` + - `:failed` - - `:invalid_prompt` + - `type: :image_generation_call` - - `:bio_policy` + The type of the image generation call. Always `image_generation_call`. - - `:vector_store_timeout` + - `:image_generation_call` - - `:invalid_image` + - `agent: Agent{ 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` + - `class BetaResponseCodeInterpreterToolCall` - - `:image_too_small` + A tool call to run code. - - `:image_parse_error` + - `class LocalShellCall` - - `:image_content_policy_violation` + A tool call to run a command on the local shell. - - `:invalid_image_mode` + - `id: String` - - `:image_file_too_large` + The unique ID of the local shell call. - - `:unsupported_image_media_type` + - `action: Action{ command, env, type, 3 more}` - - `:empty_image_file` + Execute a shell command on the server. - - `:failed_to_download_image` + - `command: Array[String]` - - `:image_file_not_found` + The command to run. - - `message: String` + - `env: Hash[Symbol, String]` - A human-readable description of the error. + Environment variables to set for the command. - - `incomplete_details: IncompleteDetails{ reason}` + - `type: :exec` - Details about why the response is incomplete. + The type of the local shell action. Always `exec`. - - `reason: :max_output_tokens | :content_filter` + - `:exec` - The reason why the response is incomplete. + - `timeout_ms: Integer` - - `:max_output_tokens` + Optional timeout in milliseconds for the command. - - `:content_filter` + - `user: String` - - `instructions: String | Array[BetaResponseInputItem]` + Optional user to run the command as. - A system (or developer) message inserted into the model's context. + - `working_directory: 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. + Optional working directory to run the command in. - - `String = String` + - `call_id: String` - A text input to the model, equivalent to a text input with the - `developer` role. + The unique ID of the local shell tool call generated by the model. - - `InputItemList = Array[BetaResponseInputItem]` + - `status: :in_progress | :completed | :incomplete` - A list of one or many input items to the model, containing - different content types. + The status of the local shell call. - - `class BetaEasyInputMessage` + - `:in_progress` - 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. + - `:completed` - - `content: String | BetaResponseInputMessageContentList` + - `:incomplete` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: :local_shell_call` - - `String = String` + The type of the local shell call. Always `local_shell_call`. - A text input to the model. + - `:local_shell_call` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `agent: Agent{ agent_name}` - A list of one or many input items to the model, containing different content - types. + The agent that produced this item. - - `class BetaResponseInputText` + - `agent_name: String` - A text input to the model. + The canonical name of the agent that produced this item. - - `text: String` + - `class LocalShellCallOutput` - The text input to the model. + The output of a local shell tool call. - - `type: :input_text` + - `id: String` - The type of the input item. Always `input_text`. + The unique ID of the local shell tool call generated by the model. - - `:input_text` + - `output: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A JSON string of the output of the local shell tool call. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: :local_shell_call_output` - - `mode: :explicit` + The type of the local shell tool call output. Always `local_shell_call_output`. - The breakpoint mode. Always `explicit`. + - `:local_shell_call_output` - - `:explicit` + - `agent: Agent{ agent_name}` - - `class BetaResponseInputImage` + 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 | :high | :auto | :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`. + - `status: :in_progress | :completed | :incomplete` - - `:low` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `:high` + - `:in_progress` - - `:auto` + - `:completed` - - `:original` + - `:incomplete` - - `type: :input_image` + - `class BetaResponseFunctionShellToolCall` - The type of the input item. Always `input_image`. + A tool call that executes one or more shell commands in a managed environment. - - `:input_image` + - `id: String` - - `file_id: String` + The unique ID of the shell tool call. Populated when this item is returned via API. - The ID of the file to be sent to the model. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `image_url: String` + The shell commands and limits that describe how to run the 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. + - `commands: Array[String]` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `max_output_length: Integer` - Marks the exact end of a reusable 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 maximum number of characters to return from each command. - - `mode: :explicit` + - `timeout_ms: Integer` - The breakpoint mode. Always `explicit`. + Optional timeout in milliseconds for the commands. - - `:explicit` + - `call_id: String` - - `class BetaResponseInputFile` + The unique ID of the shell tool call generated by the model. - A file input to the model. + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `type: :input_file` + Represents the use of a local environment to perform shell actions. - The type of the input item. Always `input_file`. + - `class BetaResponseLocalEnvironment` - - `:input_file` + Represents the use of a local environment to perform shell actions. - - `detail: :auto | :low | :high` + - `type: :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`. + The environment type. Always `local`. - - `:auto` + - `:local` - - `:low` + - `class BetaResponseContainerReference` - - `:high` + Represents a container created with /v1/containers. - - `file_data: String` + - `container_id: String` - The content of the file to be sent to the model. + - `type: :container_reference` - - `file_id: String` + The environment type. Always `container_reference`. - The ID of the file to be sent to the model. + - `:container_reference` - - `file_url: String` + - `status: :in_progress | :completed | :incomplete` - The URL of the file to be sent to the model. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `filename: String` + - `:in_progress` - The name of the file to be sent to the model. + - `:completed` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: :shell_call` - - `mode: :explicit` + The type of the item. Always `shell_call`. - The breakpoint mode. Always `explicit`. + - `:shell_call` - - `:explicit` + - `agent: Agent{ agent_name}` - - `role: :user | :assistant | :system | :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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:system` + The execution context that produced this tool call. - - `:developer` + - `class Direct` - - `phase: :commentary` + - `type: :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. + - `:direct` - - `:commentary` + - `class Program` - - `type: :message` + - `caller_id: String` - The type of the message input. Always `message`. + The call ID of the program item that produced this tool call. - - `:message` + - `type: :program` - - `class Message` + - `:program` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `created_by: String` - - `content: BetaResponseInputMessageContentList` + The ID of the entity that created this tool call. - A list of one or many input items to the model, containing different content - types. + - `class BetaResponseFunctionShellToolCallOutput` - - `role: :user | :system | :developer` + The output of a shell tool call that was emitted. - The role of the message input. One of `user`, `system`, or `developer`. + - `id: String` - - `:user` + The unique ID of the shell call output. Populated when this item is returned via API. - - `:system` + - `call_id: String` - - `:developer` + The unique ID of the shell tool call generated by the model. - - `agent: Agent{ agent_name}` + - `max_output_length: Integer` - The agent that produced this item. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `agent_name: String` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - The canonical name of the agent that produced this item. + An array of shell call output contents - - `status: :in_progress | :completed | :incomplete` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `:in_progress` + - `class Timeout` - - `:completed` + Indicates that the shell call exceeded its configured time limit. - - `:incomplete` + - `type: :timeout` - - `type: :message` + The outcome type. Always `timeout`. - The type of the message input. Always set to `message`. + - `:timeout` - - `:message` + - `class Exit` - - `class BetaResponseOutputMessage` + Indicates that the shell commands finished and returned an exit code. - An output message from the model. + - `exit_code: Integer` - - `id: String` + Exit code from the shell process. - The unique ID of the output message. + - `type: :exit` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + The outcome type. Always `exit`. - The content of the output message. + - `:exit` - - `class BetaResponseOutputText` + - `stderr: String` - A text output from the model. + The standard error output that was captured. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `stdout: String` - The annotations of the text output. + The standard output that was captured. - - `class FileCitation` + - `created_by: String` - A citation to a file. + The identifier of the actor that created the item. - - `file_id: String` + - `status: :in_progress | :completed | :incomplete` - The ID of the file. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `filename: String` + - `:in_progress` - The filename of the file cited. + - `:completed` - - `index: Integer` + - `:incomplete` - The index of the file in the list of files. + - `type: :shell_call_output` - - `type: :file_citation` + The type of the shell call output. Always `shell_call_output`. - The type of the file citation. Always `file_citation`. + - `:shell_call_output` - - `:file_citation` + - `agent: Agent{ agent_name}` - - `class URLCitation` + The agent that produced this item. - A citation for a web resource used to generate a model response. + - `agent_name: String` - - `end_index: Integer` + The canonical name of the agent that produced this item. - The index of the last character of the URL citation in the message. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `start_index: Integer` + The execution context that produced this tool call. - The index of the first character of the URL citation in the message. + - `class Direct` - - `title: String` + - `type: :direct` - The title of the web resource. + - `:direct` - - `type: :url_citation` + - `class Program` - The type of the URL citation. Always `url_citation`. + - `caller_id: String` - - `:url_citation` + The call ID of the program item that produced this tool call. - - `url: String` + - `type: :program` - The URL of the web resource. + - `:program` - - `class ContainerFileCitation` + - `created_by: String` - A citation for a container file used to generate a model response. + The identifier of the actor that created the item. - - `container_id: String` + - `class BetaResponseApplyPatchToolCall` - The ID of the container file. + A tool call that applies file diffs by creating, deleting, or updating files. - - `end_index: Integer` + - `id: String` - The index of the last character of the container file citation in the message. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `file_id: String` + - `call_id: String` - The ID of the file. + The unique ID of the apply patch tool call generated by the model. - - `filename: String` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The filename of the container file cited. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `start_index: Integer` + - `class CreateFile` - The index of the first character of the container file citation in the message. + Instruction describing how to create a file via the apply_patch tool. - - `type: :container_file_citation` + - `diff: String` - The type of the container file citation. Always `container_file_citation`. + Diff to apply. - - `:container_file_citation` + - `path: String` - - `class FilePath` + Path of the file to create. - A path to a file. + - `type: :create_file` - - `file_id: String` + Create a new file with the provided diff. - The ID of the file. + - `:create_file` - - `index: Integer` + - `class DeleteFile` - The index of the file in the list of files. + Instruction describing how to delete a file via the apply_patch tool. - - `type: :file_path` + - `path: String` - The type of the file path. Always `file_path`. + Path of the file to delete. - - `:file_path` + - `type: :delete_file` - - `text: String` + Delete the specified file. - The text output from the model. + - `:delete_file` - - `type: :output_text` + - `class UpdateFile` - The type of the output text. Always `output_text`. + Instruction describing how to update a file via the apply_patch tool. - - `:output_text` + - `diff: String` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + Diff to apply. - - `token: String` + - `path: String` - - `bytes: Array[Integer]` + Path of the file to update. - - `logprob: Float` + - `type: :update_file` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + Update an existing file with the provided diff. - - `token: String` + - `:update_file` - - `bytes: Array[Integer]` + - `status: :in_progress | :completed` - - `logprob: Float` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class BetaResponseOutputRefusal` + - `:in_progress` - A refusal from the model. + - `:completed` - - `refusal: String` + - `type: :apply_patch_call` - The refusal explanation from the model. + The type of the item. Always `apply_patch_call`. - - `type: :refusal` + - `:apply_patch_call` - The type of the refusal. Always `refusal`. + - `agent: Agent{ agent_name}` - - `:refusal` + The agent that produced this item. - - `role: :assistant` + - `agent_name: String` - The role of the output message. Always `assistant`. + The canonical name of the agent that produced this item. - - `:assistant` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `status: :in_progress | :completed | :incomplete` + The execution context that produced this tool call. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class Direct` - - `:in_progress` + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + 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 | :failed` + + The status of the apply patch tool call output. One of `completed` or `failed`. - `:completed` - - `:incomplete` + - `:failed` - - `type: :message` + - `type: :apply_patch_call_output` - The type of the output message. Always `message`. + The type of the item. Always `apply_patch_call_output`. - - `:message` + - `:apply_patch_call_output` - `agent: Agent{ agent_name}` @@ -32551,47 +43127,59 @@ Cancel a response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `caller_: Direct{ type} | Program{ 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` + - `class Direct` - - `class BetaResponseFileSearchToolCall` + - `type: :direct` - 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. + - `:direct` - - `id: String` + - `class Program` - The unique ID of the file search tool call. + - `caller_id: String` - - `queries: Array[String]` + The call ID of the program item that produced this tool call. - The queries used to search for files. + - `type: :program` - - `status: :in_progress | :searching | :completed | 2 more` + - `:program` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `created_by: String` - - `:in_progress` + The ID of the entity that created this tool call output. - - `:searching` + - `output: String` - - `:completed` + Optional textual output returned by the apply patch tool. - - `:incomplete` + - `class McpCall` - - `:failed` + An invocation of a tool on an MCP server. - - `type: :file_search_call` + - `id: String` - The type of the file search tool call. Always `file_search_call`. + The unique ID of the tool call. - - `:file_search_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: Agent{ agent_name}` @@ -32601,978 +43189,1103 @@ Cancel a response The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `approval_request_id: String` - The results of the file search 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. - - `attributes: Hash[Symbol, String | Float | bool]` + - `error: 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 error from the tool call, if any. - - `String = String` + - `output: String` - - `Float = Float` + The output from the tool call. - - `UnionMember2 = bool` + - `status: :in_progress | :completed | :incomplete | 2 more` - - `file_id: String` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The unique ID of the file. + - `:in_progress` - - `filename: String` + - `:completed` - The name of the file. + - `:incomplete` - - `score: Float` + - `:calling` - The relevance score of the file - a value between 0 and 1. + - `:failed` - - `text: String` + - `class McpListTools` - The text that was retrieved from the file. + A list of tools available on an MCP server. - - `class BetaResponseComputerToolCall` + - `id: 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. + The unique ID of the list. - - `id: String` + - `server_label: String` - The unique ID of the computer call. + The label of the MCP server. - - `call_id: String` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - An identifier used when responding to the tool call with output. + The tools available on the server. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `input_schema: untyped` - The pending safety checks for the computer call. + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + A request for human approval of a tool invocation. - `id: String` - The ID of the pending safety check. + The unique ID of the approval request. - - `code: String` + - `arguments: String` - The type of the pending safety check. + A JSON string of arguments for the tool. - - `message: String` + - `name: String` - Details about the pending safety check. + The name of the tool to run. - - `status: :in_progress | :completed | :incomplete` + - `server_label: String` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The label of the MCP server making the request. - - `:in_progress` + - `type: :mcp_approval_request` - - `:completed` + The type of the item. Always `mcp_approval_request`. - - `:incomplete` + - `:mcp_approval_request` - - `type: :computer_call` + - `agent: Agent{ agent_name}` - The type of the computer call. Always `computer_call`. + The agent that produced this item. - - `:computer_call` + - `agent_name: String` - - `action: BetaComputerAction` + The canonical name of the agent that produced this item. - A click action. + - `class McpApprovalResponse` - - `class Click` + A response to an MCP approval request. - A click action. + - `id: String` - - `button: :left | :right | :wheel | 2 more` + The unique ID of the approval response - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `approval_request_id: String` - - `:left` + The ID of the approval request being answered. - - `:right` + - `approve: bool` - - `:wheel` + Whether the request was approved. - - `:back` + - `type: :mcp_approval_response` - - `:forward` + The type of the item. Always `mcp_approval_response`. - - `type: :click` + - `:mcp_approval_response` - Specifies the event type. For a click action, this property is always `click`. + - `agent: Agent{ agent_name}` - - `:click` + The agent that produced this item. - - `x: Integer` + - `agent_name: String` - The x-coordinate where the click occurred. + The canonical name of the agent that produced this item. - - `y_: Integer` + - `reason: String` - The y-coordinate where the click occurred. + Optional reason for the decision. - - `keys: Array[String]` + - `class BetaResponseCustomToolCall` - The keys being held while clicking. + A call to a custom tool created by the model. - - `class DoubleClick` + - `class BetaResponseCustomToolCallOutputItem` - A double click action. + The output of a custom tool call from your code, being sent back to the model. - - `keys: Array[String]` + - `id: String` - The keys being held while double-clicking. + The unique ID of the custom tool call output item. - - `type: :double_click` + - `status: :in_progress | :completed | :incomplete` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:double_click` + - `:in_progress` - - `x: Integer` + - `:completed` - The x-coordinate where the double click occurred. + - `:incomplete` - - `y_: Integer` + - `created_by: String` - The y-coordinate where the double click occurred. + The identifier of the actor that created the item. - - `class Drag` + - `parallel_tool_calls: bool` - A drag action. + Whether to allow the model to run tool calls in parallel. - - `path: Array[Path{ x, y_}]` + - `temperature: Float` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + 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. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `x: Integer` + 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 x-coordinate. + - `BetaToolChoiceOptions = :none | :auto | :required` - - `y_: Integer` + Controls which (if any) tool is called by the model. - The y-coordinate. + `none` means the model will not call any tool and instead generates a message. - - `type: :drag` + `auto` means the model can pick between generating a message or calling one or + more tools. - Specifies the event type. For a drag action, this property is always set to `drag`. + `required` means the model must call one or more tools. - - `:drag` + - `:none` - - `keys: Array[String]` + - `:auto` - The keys being held while dragging the mouse. + - `:required` - - `class Keypress` + - `class BetaToolChoiceAllowed` - A collection of keypresses the model would like to perform. + Constrains the tools available to the model to a pre-defined set. - - `keys: Array[String]` + - `mode: :auto | :required` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Constrains the tools available to the model to a pre-defined set. - - `type: :keypress` + `auto` allows the model to pick from among the allowed tools and generate a + message. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + `required` requires the model to call one or more of the allowed tools. - - `:keypress` + - `:auto` - - `class Move` + - `:required` - A mouse move action. + - `tools: Array[Hash[Symbol, untyped]]` - - `type: :move` + A list of tool definitions that the model should be allowed to call. - Specifies the event type. For a move action, this property is always set to `move`. + For the Responses API, the list of tool definitions might look like: - - `:move` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `x: Integer` + - `type: :allowed_tools` - The x-coordinate to move to. + Allowed tool configuration type. Always `allowed_tools`. - - `y_: Integer` + - `:allowed_tools` - The y-coordinate to move to. + - `class BetaToolChoiceTypes` - - `keys: Array[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). - The keys being held while moving the mouse. + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `class Screenshot` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - A screenshot action. + Allowed values are: - - `type: :screenshot` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `:file_search` - - `:screenshot` + - `:web_search_preview` - - `class Scroll` + - `:computer` - A scroll action. + - `:computer_use_preview` - - `scroll_x: Integer` + - `:computer_use` - The horizontal scroll distance. + - `:web_search_preview_2025_03_11` - - `scroll_y: Integer` + - `:image_generation` - The vertical scroll distance. + - `:code_interpreter` - - `type: :scroll` + - `class BetaToolChoiceFunction` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Use this option to force the model to call a specific function. - - `:scroll` + - `name: String` - - `x: Integer` + The name of the function to call. - The x-coordinate where the scroll occurred. + - `type: :function` - - `y_: Integer` + For function calling, the type is always `function`. - The y-coordinate where the scroll occurred. + - `:function` - - `keys: Array[String]` + - `class BetaToolChoiceMcp` - The keys being held while scrolling. + Use this option to force the model to call a specific tool on a remote MCP server. - - `class Type` + - `server_label: String` - An action to type in text. + The label of the MCP server to use. - - `text: String` + - `type: :mcp` - The text to type. + For MCP tools, the type is always `mcp`. - - `type: :type` + - `:mcp` - Specifies the event type. For a type action, this property is always set to `type`. + - `name: String` - - `:type` + The name of the tool to call on the server. - - `class Wait` + - `class BetaToolChoiceCustom` - A wait action. + Use this option to force the model to call a specific custom tool. - - `type: :wait` + - `name: String` - Specifies the event type. For a wait action, this property is always set to `wait`. + The name of the custom tool to call. - - `:wait` + - `type: :custom` - - `actions: BetaComputerActionList` + For custom tool calling, the type is always `custom`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `:custom` - - `class Click` + - `class BetaSpecificProgrammaticToolCallingParam` - A click action. + - `type: :programmatic_tool_calling` - - `class DoubleClick` + The tool to call. Always `programmatic_tool_calling`. - A double click action. + - `:programmatic_tool_calling` - - `class Drag` + - `class BetaToolChoiceApplyPatch` - A drag action. + Forces the model to call the apply_patch tool when executing a tool call. - - `class Keypress` + - `type: :apply_patch` - A collection of keypresses the model would like to perform. + The tool to call. Always `apply_patch`. - - `class Move` + - `:apply_patch` - A mouse move action. + - `class BetaToolChoiceShell` - - `class Screenshot` + Forces the model to call the shell tool when a tool call is required. - A screenshot action. + - `type: :shell` - - `class Scroll` + The tool to call. Always `shell`. - A scroll action. + - `:shell` - - `class Type` + - `tools: Array[BetaTool]` - An action to type in text. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `class Wait` + We support the following categories of tools: - A wait action. + - **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. - - `agent: Agent{ agent_name}` + - `class BetaFunctionTool` - The agent that produced this item. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `agent_name: String` + - `class BetaFileSearchTool` - 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). - - `class ComputerCallOutput` + - `class BetaComputerTool` - The output of a computer tool call. + 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` + - `class BetaComputerUsePreviewTool` - 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` + - `class BetaWebSearchTool` - A computer screenshot image used with the computer use tool. + 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: :computer_screenshot` + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `class ImageGeneration` - - `:computer_screenshot` + A tool that generates images using the GPT image models. - - `file_id: String` + - `class LocalShell` - The identifier of an uploaded file that contains the screenshot. + A tool that allows the model to execute shell commands in a local environment. - - `image_url: String` + - `class BetaFunctionShellTool` - The URL of the screenshot image. + A tool that allows the model to execute shell commands. - - `type: :computer_call_output` + - `class BetaCustomTool` - The type of the computer tool call output. Always `computer_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) - - `:computer_call_output` + - `class BetaNamespaceTool` - - `id: String` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call output. + - `class BetaToolSearchTool` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + Hosted or BYOT tool search configuration for deferred tools. - The safety checks reported by the API that have been acknowledged by the developer. + - `class BetaWebSearchPreviewTool` - - `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 pending safety check. + - `class BetaApplyPatchTool` - - `code: String` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the pending safety check. + - `top_p: Float` - - `message: 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. - Details about the pending safety check. + We generally recommend altering this or `temperature` but not both. - - `agent: Agent{ agent_name}` + - `background: bool` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `agent_name: String` + - `completed_at: Float` - 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`. - - `status: :in_progress | :completed | :incomplete` + - `conversation: Conversation{ id}` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `:in_progress` + - `id: String` - - `:completed` + The unique ID of the conversation that this response was associated with. - - `:incomplete` + - `max_output_tokens: Integer` - - `class BetaResponseFunctionWebSearch` + 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 results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `max_tool_calls: Integer` - - `id: String` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The unique ID of the web search tool call. + - `moderation: Moderation{ input, output}` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + Moderation results for the response input and output, if moderated completions were requested. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `class Search` + Moderation for the response input. - Action type "search" - Performs a web search query. + - `class ModerationResult` - - `type: :search` + A moderation result produced for the response input or output. - The action type. + - `categories: Hash[Symbol, bool]` - - `:search` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `queries: Array[String]` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - The search queries. + Which modalities of input are reflected by the score for each category. - - `query: String` + - `:text` - The search query. + - `:image` - - `sources: Array[Source{ type, url}]` + - `category_scores: Hash[Symbol, Float]` - The sources used in the search. + A dictionary of moderation categories to scores. - - `type: :url` + - `flagged: bool` - The type of source. Always `url`. + A boolean indicating whether the content was flagged by any category. - - `:url` + - `model: String` - - `url: String` + The moderation model that produced this result. - The URL of the source. + - `type: :moderation_result` - - `class OpenPage` + The object type, which was always `moderation_result` for successful moderation results. - Action type "open_page" - Opens a specific URL from search results. + - `:moderation_result` - - `type: :open_page` + - `class Error` - The action type. + An error produced while attempting moderation for the response input or output. - - `:open_page` + - `code: String` - - `url: String` + The error code. - The URL opened by the model. + - `message: String` - - `class FindInPage` + The error message. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: :error` - - `pattern: String` + The object type, which was always `error` for moderation failures. - The pattern or text to search for within the page. + - `:error` - - `type: :find_in_page` + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - The action type. + Moderation for the response output. - - `:find_in_page` + - `class ModerationResult` - - `url: String` + A moderation result produced for the response input or output. - The URL of the page searched for the pattern. + - `categories: Hash[Symbol, bool]` - - `status: :in_progress | :searching | :completed | :failed` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The status of the web search tool call. + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `:in_progress` + Which modalities of input are reflected by the score for each category. - - `:searching` + - `:text` - - `:completed` + - `:image` - - `:failed` + - `category_scores: Hash[Symbol, Float]` - - `type: :web_search_call` + A dictionary of moderation categories to scores. - The type of the web search tool call. Always `web_search_call`. + - `flagged: bool` - - `:web_search_call` + A boolean indicating whether the content was flagged by any category. - - `agent: Agent{ 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. - - `class BetaResponseFunctionToolCall` + - `:moderation_result` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class Error` - - `arguments: String` + An error produced while attempting moderation for the response input or output. - A JSON string of the arguments to pass to the function. + - `code: String` - - `call_id: String` + The error code. - The unique ID of the function tool call generated by the model. + - `message: String` - - `name: String` + The error message. - The name of the function to run. + - `type: :error` - - `type: :function_call` + The object type, which was always `error` for moderation failures. - The type of the function tool call. Always `function_call`. + - `:error` - - `:function_call` + - `previous_response_id: 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 function tool call. + - `prompt: BetaResponsePrompt` - - `agent: Agent{ agent_name}` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The agent that produced this item. + - `id: String` - - `agent_name: String` + The unique identifier of the prompt template to use. - The canonical name of the agent that produced this item. + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The execution context that produced this tool call. + - `String = String` - - `class Direct` + - `class BetaResponseInputText` - - `type: :direct` + A text input to the model. - - `:direct` + - `class BetaResponseInputImage` - - `class Program` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `caller_id: String` + - `class BetaResponseInputFile` - The call ID of the program item that produced this tool call. + A file input to the model. - - `type: :program` + - `version: String` - - `:program` + Optional version of the prompt template. - - `namespace: String` + - `prompt_cache_key: String` - The namespace of the function to run. + 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). - - `status: :in_progress | :completed | :incomplete` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `:in_progress` + - `mode: :implicit | :explicit` - - `:completed` + Whether implicit prompt-cache breakpoints were enabled. - - `:incomplete` + - `:implicit` - - `class FunctionCallOutput` + - `:explicit` - The output of a function tool call. + - `ttl: :"30m"` - - `call_id: String` + The minimum lifetime applied to each cache breakpoint. - The unique ID of the function tool call generated by the model. + - `:"30m"` - - `output: String | BetaResponseFunctionCallOutputItemList` + - `prompt_cache_retention: :in_memory | :"24h"` - Text, image, or file output of the function tool call. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `String = 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. - A JSON string of the output of the function tool call. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - An array of content outputs (text, image, file) for the function tool call. + - `:in_memory` - - `class BetaResponseInputTextContent` + - `:"24h"` - A text input to the model. + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - - `text: String` + **gpt-5 and o-series models only** - The text input to the model. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `type: :input_text` + - `context: :auto | :current_turn | :all_turns` - The type of the input item. Always `input_text`. + 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. - - `:input_text` + - `:auto` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:current_turn` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:all_turns` - - `mode: :explicit` + - `effort: :none | :minimal | :low | 4 more` - The breakpoint mode. Always `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. - - `:explicit` + - `:none` - - `class BetaResponseInputImageContent` + - `:minimal` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:low` - - `type: :input_image` + - `:medium` - The type of the input item. Always `input_image`. + - `:high` - - `:input_image` + - `:xhigh` - - `detail: :low | :high | :auto | :original` + - `:max` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `generate_summary: :auto | :concise | :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`. - `:auto` - - `:original` + - `:concise` - - `file_id: String` + - `:detailed` - The ID of the file to be sent to the model. + - `mode: String | :standard | :pro` - - `image_url: String` + Controls the reasoning execution mode for the request. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + When returned on a response, this is the effective execution mode. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `String = 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. + - `Mode = :standard | :pro` - - `mode: :explicit` + Controls the reasoning execution mode for the request. - The breakpoint mode. Always `explicit`. + When returned on a response, this is the effective execution mode. - - `:explicit` + - `:standard` - - `class BetaResponseInputFileContent` + - `:pro` - A file input to the model. + - `summary: :auto | :concise | :detailed` - - `type: :input_file` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The type of the input item. Always `input_file`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `:input_file` + - `:auto` - - `detail: :auto | :low | :high` + - `:concise` - 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`. + - `:detailed` - - `:auto` + - `safety_identifier: String` - - `:low` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `:high` + - `service_tier: :auto | :default | :flex | 2 more` - - `file_data: String` + Specifies the processing type used for serving the request. - The base64-encoded data of the file to be sent 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](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'. - - `file_id: 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 ID of the file to be sent to the model. + - `:auto` - - `file_url: String` + - `:default` - The URL of the file to be sent to the model. + - `:flex` - - `filename: String` + - `:scale` - The name of the file to be sent to the model. + - `:priority` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `status: BetaResponseStatus` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `mode: :explicit` + - `:completed` - The breakpoint mode. Always `explicit`. + - `:failed` - - `:explicit` + - `:in_progress` - - `type: :function_call_output` + - `:cancelled` - The type of the function tool call output. Always `function_call_output`. + - `:queued` - - `:function_call_output` + - `:incomplete` - - `id: String` + - `text: BetaResponseTextConfig` - The unique ID of the function tool call output. Populated when this item is returned via API. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `agent: Agent{ agent_name}` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The agent that produced this item. + - `format_: BetaResponseFormatTextConfig` - - `agent_name: String` + An object specifying the format that the model must output. - The canonical name of 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). - - `caller_: Direct{ type} | Program{ caller_id, type}` + The default format is `{ "type": "text" }` with no additional options. - The execution context that produced this tool call. + **Not recommended for gpt-4o and newer models:** - - `class Direct` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `type: :direct` + - `class Text` - The caller type. Always `direct`. + Default response format. Used to generate text responses. - - `:direct` + - `type: :text` - - `class Program` + 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. + - `class BetaResponseFormatTextJSONSchemaConfig` - - `type: :program` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The caller type. Always `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. - - `status: :in_progress | :completed | :incomplete` + - `schema: Hash[Symbol, untyped]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:in_progress` + - `type: :json_schema` - - `:completed` + The type of response format being defined. Always `json_schema`. - - `:incomplete` + - `:json_schema` - - `class AgentMessage` + - `description: String` - A message routed between agents. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `author: String` + - `strict: bool` - The sending agent identity. + 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). - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + - `class JSONObject` - Plaintext, image, or encrypted content sent between 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. - - `class BetaResponseInputTextContent` + - `type: :json_object` - A text input to the model. + The type of response format being defined. Always `json_object`. - - `class BetaResponseInputImageContent` + - `:json_object` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `verbosity: :low | :medium | :high` - - `class EncryptedContent` + 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`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `:low` - - `encrypted_content: String` + - `:medium` - Opaque encrypted content. + - `:high` - - `type: :encrypted_content` + - `top_logprobs: Integer` - The type of the input item. Always `encrypted_content`. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `:encrypted_content` + - `truncation: :auto | :disabled` - - `recipient: String` + The truncation strategy to use for the model response. - The destination agent identity. + - `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: :agent_message` + - `:auto` - The item type. Always `agent_message`. + - `:disabled` - - `:agent_message` + - `usage: BetaResponseUsage` - - `id: String` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The unique ID of this agent message item. + - `input_tokens: Integer` - - `agent: Agent{ agent_name}` + The number of input tokens. - The agent that produced this item. + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - - `agent_name: String` + A detailed breakdown of the input tokens. - The canonical name of the agent that produced this item. + - `cache_write_tokens: Integer` - - `class MultiAgentCall` + The number of input tokens that were written to the cache. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `cached_tokens: Integer` - The multi-agent action that was executed. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `:spawn_agent` + - `output_tokens: Integer` - - `:interrupt_agent` + The number of output tokens. - - `:list_agents` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - - `:send_message` + A detailed breakdown of the output tokens. - - `:followup_task` + - `reasoning_tokens: Integer` - - `:wait_agent` + The number of reasoning tokens. - - `arguments: String` + - `total_tokens: Integer` - The action arguments as a JSON string. + The total number of tokens used. - - `call_id: String` + - `user: String` - The unique ID linking this call to its 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: :multi_agent_call` +### Beta Response Apply Patch Tool Call - The item type. Always `multi_agent_call`. +- `class BetaResponseApplyPatchToolCall` - - `:multi_agent_call` + A tool call that applies file diffs by creating, deleting, or updating files. - `id: String` - The unique ID of this multi-agent call. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` + - `call_id: String` - The agent that produced this item. + The unique ID of the apply patch tool call generated by the model. - - `agent_name: String` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The canonical name of the agent that produced this item. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class MultiAgentCallOutput` + - `class CreateFile` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + Instruction describing how to create a file via the apply_patch tool. - The multi-agent action that produced this result. + - `diff: String` - - `:spawn_agent` + Diff to apply. - - `:interrupt_agent` + - `path: String` - - `:list_agents` + Path of the file to create. - - `:send_message` + - `type: :create_file` - - `:followup_task` + Create a new file with the provided diff. - - `:wait_agent` + - `:create_file` - - `call_id: String` + - `class DeleteFile` - The unique ID of the multi-agent call. + Instruction describing how to delete a file via the apply_patch tool. - - `output: Array[Output{ text, type, annotations}]` + - `path: String` - Text output returned by the multi-agent action. + Path of the file to delete. - - `text: String` + - `type: :delete_file` - The text content. + Delete the specified file. - - `type: :output_text` + - `:delete_file` - The content type. Always `output_text`. + - `class UpdateFile` - - `:output_text` + Instruction describing how to update a file via the apply_patch tool. - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `diff: String` - Citations associated with the text content. + Diff to apply. - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `path: String` - - `file_id: String` + Path of the file to update. - The ID of the file. + - `type: :update_file` - - `filename: String` + Update an existing file with the provided diff. - The filename of the file cited. + - `:update_file` - - `index: Integer` + - `status: :in_progress | :completed` - The index of the file in the list of files. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `type: :file_citation` + - `:in_progress` - The citation type. Always `file_citation`. + - `:completed` - - `:file_citation` + - `type: :apply_patch_call` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + The type of the item. Always `apply_patch_call`. - - `end_index: Integer` + - `:apply_patch_call` - The index of the last character of the citation in the message. + - `agent: Agent{ agent_name}` - - `start_index: Integer` + The agent that produced this item. - The index of the first character of the citation in the message. + - `agent_name: String` - - `title: String` + The canonical name of the agent that produced this item. - The title of the cited resource. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `type: :url_citation` + The execution context that produced this tool call. - The citation type. Always `url_citation`. + - `class Direct` - - `:url_citation` + - `type: :direct` - - `url: String` + - `:direct` - The URL of the cited resource. + - `class Program` - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `caller_id: String` - - `container_id: String` + The call ID of the program item that produced this tool call. - The ID of the container. + - `type: :program` - - `end_index: Integer` + - `:program` - The index of the last character of the citation in the message. + - `created_by: String` - - `file_id: String` + The ID of the entity that created this tool call. - The ID of the container file. +### Beta Response Apply Patch Tool Call Output - - `filename: String` +- `class BetaResponseApplyPatchToolCallOutput` - The filename of the container file cited. + The output emitted by an apply patch tool call. - - `start_index: Integer` + - `id: String` - The index of the first character of the citation in the message. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `type: :container_file_citation` + - `call_id: String` - The citation type. Always `container_file_citation`. + The unique ID of the apply patch tool call generated by the model. - - `:container_file_citation` + - `status: :completed | :failed` - - `type: :multi_agent_call_output` + The status of the apply patch tool call output. One of `completed` or `failed`. - The item type. Always `multi_agent_call_output`. + - `:completed` - - `:multi_agent_call_output` + - `:failed` - - `id: String` + - `type: :apply_patch_call_output` - The unique ID of this multi-agent call output. + The type of the item. Always `apply_patch_call_output`. + + - `:apply_patch_call_output` - `agent: Agent{ agent_name}` @@ -33582,1402 +44295,1365 @@ Cancel a response The canonical name of the agent that produced this item. - - `class ToolSearchCall` - - - `arguments: untyped` - - The arguments supplied to the tool search call. - - - `type: :tool_search_call` - - The item type. Always `tool_search_call`. - - - `:tool_search_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of this tool search call. + - `class Direct` - - `agent: Agent{ agent_name}` + - `type: :direct` - The agent that produced this item. + - `:direct` - - `agent_name: String` + - `class Program` - The canonical name of the agent that produced this item. + - `caller_id: String` - - `call_id: String` + The call ID of the program item that produced this tool call. - The unique ID of the tool search call generated by the model. + - `type: :program` - - `execution: :server | :client` + - `:program` - Whether tool search was executed by the server or by the client. + - `created_by: String` - - `:server` + The ID of the entity that created this tool call output. - - `:client` + - `output: String` - - `status: :in_progress | :completed | :incomplete` + Optional textual output returned by the apply patch tool. - The status of the tool search call. +### Beta Response Audio Delta Event - - `:in_progress` +- `class BetaResponseAudioDeltaEvent` - - `:completed` + Emitted when there is a partial audio response. - - `:incomplete` + - `delta: String` - - `class BetaResponseToolSearchOutputItemParam` + A chunk of Base64 encoded response audio bytes. - - `tools: Array[BetaTool]` + - `sequence_number: Integer` - The loaded tool definitions returned by the tool search output. + A sequence number for this chunk of the stream response. - - `class BetaFunctionTool` + - `type: :"response.audio.delta"` - 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 event. Always `response.audio.delta`. - - `name: String` + - `:"response.audio.delta"` - The name of the function to call. + - `agent: Agent{ agent_name}` - - `parameters: Hash[Symbol, untyped]` + The agent that owns this multi-agent streaming event. - A JSON schema object describing the parameters of the function. + - `agent_name: String` - - `strict: bool` + The canonical name of the agent that produced this item. - Whether strict parameter validation is enforced for this function tool. +### Beta Response Audio Done Event - - `type: :function` +- `class BetaResponseAudioDoneEvent` - The type of the function tool. Always `function`. + Emitted when the audio response is complete. - - `:function` + - `sequence_number: Integer` - - `allowed_callers: Array[:direct | :programmatic]` + The sequence number of the delta. - The tool invocation context(s). + - `type: :"response.audio.done"` - - `:direct` + The type of the event. Always `response.audio.done`. - - `:programmatic` + - `:"response.audio.done"` - - `defer_loading: bool` + - `agent: Agent{ agent_name}` - Whether this function is deferred and loaded via tool search. + The agent that owns this multi-agent streaming event. - - `description: 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: Hash[Symbol, untyped]` +### Beta Response Audio Transcript Delta Event - A JSON schema object describing the JSON value encoded in string outputs for this function. +- `class BetaResponseAudioTranscriptDeltaEvent` - - `class BetaFileSearchTool` + Emitted when there is a partial transcript of audio. - 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). + - `delta: String` - - `type: :file_search` + The partial transcript of the audio response. - The type of the file search tool. Always `file_search`. + - `sequence_number: Integer` - - `:file_search` + The sequence number of this event. - - `vector_store_ids: Array[String]` + - `type: :"response.audio.transcript.delta"` - The IDs of the vector stores to search. + The type of the event. Always `response.audio.transcript.delta`. - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `:"response.audio.transcript.delta"` - A filter to apply. + - `agent: Agent{ agent_name}` - - `class ComparisonFilter` + The agent that owns this multi-agent streaming event. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `agent_name: String` - - `key: String` + The canonical name of the agent that produced this item. - The key to compare against the value. +### Beta Response Audio Transcript Done Event - - `type: :eq | :ne | :gt | 5 more` +- `class BetaResponseAudioTranscriptDoneEvent` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Emitted when the full audio transcript is completed. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `sequence_number: Integer` - - `:eq` + The sequence number of this event. - - `:ne` + - `type: :"response.audio.transcript.done"` - - `:gt` + The type of the event. Always `response.audio.transcript.done`. - - `:gte` + - `:"response.audio.transcript.done"` - - `:lt` + - `agent: Agent{ 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 | Float | bool | Array[untyped]` +### Beta Response Code Interpreter Call Code Delta Event - The value to compare against the attribute key; supports string, number, or boolean types. +- `class BetaResponseCodeInterpreterCallCodeDeltaEvent` - - `String = String` + Emitted when a partial code snippet is streamed by the code interpreter. - - `Float = Float` + - `delta: String` - - `UnionMember2 = bool` + The partial code snippet being streamed by the code interpreter. - - `UnionMember3 = Array[untyped]` + - `item_id: String` - - `class CompoundFilter` + The unique identifier of the code interpreter tool call item. - Combine multiple filters using `and` or `or`. + - `output_index: Integer` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The index of the output item in the response for which the code is being streamed. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `sequence_number: Integer` - - `class ComparisonFilter` + The sequence number of this event, used to order streaming events. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: :"response.code_interpreter_call_code.delta"` - - `key: String` + The type of the event. Always `response.code_interpreter_call_code.delta`. - The key to compare against the value. + - `:"response.code_interpreter_call_code.delta"` - - `type: :eq | :ne | :gt | 5 more` + - `agent: Agent{ agent_name}` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The agent that owns this multi-agent streaming event. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `agent_name: String` - - `:eq` + The canonical name of the agent that produced this item. - - `:ne` +### Beta Response Code Interpreter Call Code Done Event - - `:gt` +- `class BetaResponseCodeInterpreterCallCodeDoneEvent` - - `:gte` + Emitted when the code snippet is finalized by the code interpreter. - - `:lt` + - `code: String` - - `:lte` + The final code snippet output by the code interpreter. - - `:in` + - `item_id: String` - - `:nin` + The unique identifier of the code interpreter tool call item. - - `value: String | Float | bool | Array[untyped]` + - `output_index: Integer` - The value to compare against the attribute key; supports string, number, or boolean types. + The index of the output item in the response for which the code is finalized. - - `String = String` + - `sequence_number: Integer` - - `Float = Float` + The sequence number of this event, used to order streaming events. - - `UnionMember2 = bool` + - `type: :"response.code_interpreter_call_code.done"` - - `UnionMember3 = Array[untyped]` + The type of the event. Always `response.code_interpreter_call_code.done`. - - `UnionMember1 = untyped` + - `:"response.code_interpreter_call_code.done"` - - `type: :and | :or` + - `agent: Agent{ agent_name}` - Type of operation: `and` or `or`. + The agent that owns this multi-agent streaming event. - - `:and` + - `agent_name: String` - - `:or` + The canonical name of the agent that produced this item. - - `max_num_results: Integer` +### Beta Response Code Interpreter Call Completed Event - The maximum number of results to return. This number should be between 1 and 50 inclusive. +- `class BetaResponseCodeInterpreterCallCompletedEvent` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + Emitted when the code interpreter call is completed. - Ranking options for search. + - `item_id: String` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + The unique identifier of the code interpreter tool call item. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `output_index: Integer` - - `embedding_weight: Float` + The index of the output item in the response for which the code interpreter call is completed. - The weight of the embedding in the reciprocal ranking fusion. + - `sequence_number: Integer` - - `text_weight: Float` + The sequence number of this event, used to order streaming events. - The weight of the text in the reciprocal ranking fusion. + - `type: :"response.code_interpreter_call.completed"` - - `ranker: :auto | :"default-2024-11-15"` + The type of the event. Always `response.code_interpreter_call.completed`. - The ranker to use for the file search. + - `:"response.code_interpreter_call.completed"` - - `:auto` + - `agent: Agent{ agent_name}` - - `:"default-2024-11-15"` + The agent that owns this multi-agent streaming event. - - `score_threshold: Float` + - `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. - - `class BetaComputerTool` +### Beta Response Code Interpreter Call In Progress Event - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `class BetaResponseCodeInterpreterCallInProgressEvent` - - `type: :computer` + Emitted when a code interpreter call is in progress. - The type of the computer tool. Always `computer`. + - `item_id: String` - - `:computer` + The unique identifier of the code interpreter tool call item. - - `class BetaComputerUsePreviewTool` + - `output_index: Integer` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the output item in the response for which the code interpreter call is in progress. - - `display_height: Integer` + - `sequence_number: Integer` - The height of the computer display. + The sequence number of this event, used to order streaming events. - - `display_width: Integer` + - `type: :"response.code_interpreter_call.in_progress"` - The width of the computer display. + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `environment: :windows | :mac | :linux | 2 more` + - `:"response.code_interpreter_call.in_progress"` - The type of computer environment to control. + - `agent: Agent{ agent_name}` - - `:windows` + The agent that owns this multi-agent streaming event. - - `:mac` + - `agent_name: String` - - `:linux` + The canonical name of the agent that produced this item. - - `:ubuntu` +### Beta Response Code Interpreter Call Interpreting Event - - `:browser` +- `class BetaResponseCodeInterpreterCallInterpretingEvent` - - `type: :computer_use_preview` + Emitted when the code interpreter is actively interpreting the code snippet. - The type of the computer use tool. Always `computer_use_preview`. + - `item_id: String` - - `:computer_use_preview` + The unique identifier of the code interpreter tool call item. - - `class BetaWebSearchTool` + - `output_index: Integer` - 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 index of the output item in the response for which the code interpreter is interpreting code. - - `type: :web_search | :web_search_2025_08_26` + - `sequence_number: Integer` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The sequence number of this event, used to order streaming events. - - `:web_search` + - `type: :"response.code_interpreter_call.interpreting"` - - `:web_search_2025_08_26` + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `filters: Filters{ allowed_domains}` + - `:"response.code_interpreter_call.interpreting"` - Filters for the search. + - `agent: Agent{ agent_name}` - - `allowed_domains: Array[String]` + The agent that owns this multi-agent streaming event. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `agent_name: String` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The canonical name of the agent that produced this item. - - `search_context_size: :low | :medium | :high` +### Beta Response Code Interpreter 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. +- `class BetaResponseCodeInterpreterToolCall` - - `:low` + A tool call to run code. - - `:medium` + - `id: String` - - `:high` + The unique ID of the code interpreter tool call. - - `user_location: UserLocation{ city, country, region, 2 more}` + - `code: String` - The approximate location of the user. + The code to run, or null if not available. - - `city: String` + - `container_id: String` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the container used to run the code. - - `country: String` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `region: String` + - `class Logs` - Free text input for the region of the user, e.g. `California`. + The logs output from the code interpreter. - - `timezone: String` + - `logs: String` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The logs output from the code interpreter. - - `type: :approximate` + - `type: :logs` - The type of location approximation. Always `approximate`. + The type of the output. Always `logs`. - - `:approximate` + - `:logs` - - `class Mcp` + - `class Image` - 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 image output from the code interpreter. - - `server_label: String` + - `type: :image` - A label for this MCP server, used to identify it in tool calls. + The type of the output. Always `image`. - - `type: :mcp` + - `:image` - The type of the MCP tool. Always `mcp`. + - `url: String` - - `:mcp` + The URL of the image output from the code interpreter. - - `allowed_callers: Array[:direct | :programmatic]` + - `status: :in_progress | :completed | :incomplete | 2 more` - The tool invocation context(s). + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `:direct` + - `:in_progress` - - `:programmatic` + - `:completed` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `:incomplete` - List of allowed tool names or a filter object. + - `:interpreting` - - `McpAllowedTools = Array[String]` + - `:failed` - A string array of allowed tool names + - `type: :code_interpreter_call` - - `class McpToolFilter` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A filter object to specify which tools are allowed. + - `:code_interpreter_call` - - `read_only: bool` + - `agent: Agent{ 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: Array[String]` + - `agent_name: String` - List of allowed tool names. + The canonical name of the agent that produced this item. - - `authorization: String` +### Beta Response Compaction 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. +- `class BetaResponseCompactionItem` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/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). + - `id: String` - Currently supported `connector_id` values are: + The unique ID of the compaction 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` + - `encrypted_content: String` - - `:connector_dropbox` + The encrypted content that was produced by compaction. - - `:connector_gmail` + - `type: :compaction` - - `:connector_googlecalendar` + The type of the item. Always `compaction`. - - `:connector_googledrive` + - `:compaction` - - `:connector_microsoftteams` + - `agent: Agent{ agent_name}` - - `:connector_outlookcalendar` + The agent that produced this item. - - `:connector_outlookemail` + - `agent_name: String` - - `:connector_sharepoint` + The canonical name of the agent that produced this item. - - `defer_loading: bool` + - `created_by: String` - Whether this MCP tool is deferred and discovered via tool search. + The identifier of the actor that created the item. - - `headers: Hash[Symbol, String]` +### Beta Response Compaction Item Param - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. +- `class BetaResponseCompactionItemParam` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - Specify which of the MCP server's tools require approval. + - `encrypted_content: String` - - `class McpToolApprovalFilter` + The encrypted content of the compaction summary. - 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: :compaction` - - `always: Always{ read_only, tool_names}` + The type of the item. Always `compaction`. - A filter object to specify which tools are allowed. + - `:compaction` - - `read_only: bool` + - `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 compaction item. - - `tool_names: Array[String]` + - `agent: Agent{ agent_name}` - List of allowed tool names. + The agent that produced this item. - - `never: Never{ 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: bool` +### Beta Response Completed 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. +- `class BetaResponseCompletedEvent` - - `tool_names: Array[String]` + Emitted when the model response is complete. - List of allowed tool names. + - `response: BetaResponse` - - `McpToolApprovalSetting = :always | :never` + Properties of the completed 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. + - `id: String` - - `:always` + Unique identifier for this Response. - - `:never` + - `created_at: Float` - - `server_description: String` + Unix timestamp (in seconds) of when this Response was created. - Optional description of the MCP server, used to provide more context. + - `error: BetaResponseError` - - `server_url: String` + An error object returned when the model fails to generate a Response. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `tunnel_id: String` + The error code for the response. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `:server_error` - - `class CodeInterpreter` + - `:rate_limit_exceeded` - A tool that runs Python code to help generate a response to a prompt. + - `:invalid_prompt` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `:bio_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. + - `:vector_store_timeout` - - `String = String` + - `:invalid_image` - The container ID. + - `:invalid_image_format` - - `class CodeInterpreterToolAuto` + - `:invalid_base64_image` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `:invalid_image_url` - - `type: :auto` + - `:image_too_large` - Always `auto`. + - `:image_too_small` - - `:auto` + - `:image_parse_error` - - `file_ids: Array[String]` + - `:image_content_policy_violation` - An optional list of uploaded files to make available to your code. + - `:invalid_image_mode` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:image_file_too_large` - The memory limit for the code interpreter container. + - `:unsupported_image_media_type` - - `:"1g"` + - `:empty_image_file` - - `:"4g"` + - `:failed_to_download_image` - - `:"16g"` + - `:image_file_not_found` - - `:"64g"` + - `message: String` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + A human-readable description of the error. - Network access policy for the container. + - `incomplete_details: IncompleteDetails{ reason}` - - `class BetaContainerNetworkPolicyDisabled` + Details about why the response is incomplete. - - `type: :disabled` + - `reason: :max_output_tokens | :content_filter` - Disable outbound network access. Always `disabled`. + The reason why the response is incomplete. - - `:disabled` + - `:max_output_tokens` - - `class BetaContainerNetworkPolicyAllowlist` + - `:content_filter` - - `allowed_domains: Array[String]` + - `instructions: String | Array[BetaResponseInputItem]` - A list of allowed domains when type is `allowlist`. + A system (or developer) message inserted into the model's context. - - `type: :allowlist` + 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. - Allow outbound network access only to specified domains. Always `allowlist`. + - `String = String` - - `:allowlist` + A text input to the model, equivalent to a text input with the + `developer` role. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `InputItemList = Array[BetaResponseInputItem]` - Optional domain-scoped secrets for allowlisted domains. + A list of one or many input items to the model, containing + different content types. - - `domain: String` + - `class BetaEasyInputMessage` - The domain associated with the secret. + 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 | BetaResponseInputMessageContentList` - The name of the secret to inject for the domain. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `value: String` + - `String = String` - The secret value to inject for the domain. + A text input to the model. - - `type: :code_interpreter` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - The type of the code interpreter tool. Always `code_interpreter`. + A list of one or many input items to the model, containing different content + types. - - `:code_interpreter` + - `class BetaResponseInputText` - - `allowed_callers: Array[:direct | :programmatic]` + A text input to the model. - The tool invocation context(s). + - `text: String` - - `:direct` + The text input to the model. - - `:programmatic` + - `type: :input_text` - - `class ProgrammaticToolCalling` + The type of the input item. Always `input_text`. - - `type: :programmatic_tool_calling` + - `:input_text` - The type of the tool. Always `programmatic_tool_calling`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:programmatic_tool_calling` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class ImageGeneration` + - `mode: :explicit` - A tool that generates images using the GPT image models. + The breakpoint mode. Always `explicit`. - - `type: :image_generation` + - `:explicit` - The type of the image generation tool. Always `image_generation`. + - `class BetaResponseInputImage` - - `:image_generation` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `action: :generate | :edit | :auto` + - `detail: :low | :high | :auto | :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: :transparent | :opaque | :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. + - `type: :input_image` - 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 input item. Always `input_image`. - - `:transparent` + - `:input_image` - - `:opaque` + - `file_id: String` - - `:auto` + The ID of the file to be sent to the model. - - `input_fidelity: :high | :low` + - `image_url: 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 of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `:high` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:low` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `mode: :explicit` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The breakpoint mode. Always `explicit`. - - `file_id: String` + - `:explicit` - File ID for the mask image. + - `class BetaResponseInputFile` - - `image_url: String` + A file input to the model. - Base64-encoded mask image. + - `type: :input_file` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The type of the input item. Always `input_file`. - The image generation model to use. Default: `gpt-image-1`. + - `:input_file` - - `String = String` + - `detail: :auto | :low | :high` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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` - - `:"gpt-image-1"` + - `:low` - - `:"gpt-image-1-mini"` + - `:high` - - `:"gpt-image-2"` + - `file_data: String` - - `:"gpt-image-2-2026-04-21"` + The content of the file to be sent to the model. - - `:"gpt-image-1.5"` + - `file_id: String` - - `:"chatgpt-image-latest"` + The ID of the file to be sent to the model. - - `moderation: :auto | :low` + - `file_url: String` - Moderation level for the generated image. Default: `auto`. + The URL of the file to be sent to the model. - - `:auto` + - `filename: String` - - `:low` + The name of the file to be sent to the model. - - `output_compression: Integer` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - Compression level for the output image. Default: 100. + Marks the exact end of a reusable 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_format: :png | :webp | :jpeg` + - `mode: :explicit` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The breakpoint mode. Always `explicit`. - - `:png` + - `:explicit` - - `:webp` + - `role: :user | :assistant | :system | :developer` - - `:jpeg` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `partial_images: Integer` + - `:user` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `:assistant` - - `quality: :low | :medium | :high | :auto` + - `:system` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `:developer` - - `:low` + - `phase: :commentary | :final_answer` - - `:medium` + 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. - - `:high` + - `:commentary` - - `:auto` + - `:final_answer` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `type: :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`. + The type of the message input. Always `message`. - - `String = String` + - `:message` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `class 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`. + 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. - - `:"1024x1024"` + - `content: BetaResponseInputMessageContentList` - - `:"1024x1536"` + A list of one or many input items to the model, containing different content + types. - - `:"1536x1024"` + - `role: :user | :system | :developer` - - `:auto` + The role of the message input. One of `user`, `system`, or `developer`. - - `class LocalShell` + - `:user` - A tool that allows the model to execute shell commands in a local environment. + - `:system` - - `type: :local_shell` + - `:developer` - The type of the local shell tool. Always `local_shell`. + - `agent: Agent{ agent_name}` - - `:local_shell` + The agent that produced this item. - - `class BetaFunctionShellTool` + - `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` + - `status: :in_progress | :completed | :incomplete` - The type of the shell tool. Always `shell`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:shell` + - `:in_progress` - - `allowed_callers: Array[:direct | :programmatic]` + - `:completed` - The tool invocation context(s). + - `:incomplete` - - `:direct` + - `type: :message` - - `:programmatic` + The type of the message input. Always set to `message`. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `:message` - - `class BetaContainerAuto` + - `class BetaResponseOutputMessage` - - `type: :container_auto` + An output message from the model. - Automatically creates a container for this request + - `id: String` - - `:container_auto` + The unique ID of the output message. - - `file_ids: Array[String]` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - An optional list of uploaded files to make available to your code. + The content of the output message. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class BetaResponseOutputText` - The memory limit for the container. + A text output from the model. - - `:"1g"` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:"4g"` + The annotations of the text output. - - `:"16g"` + - `class FileCitation` - - `:"64g"` + A citation to a file. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `file_id: String` - Network access policy for the container. + The ID of the file. - - `class BetaContainerNetworkPolicyDisabled` + - `filename: String` - - `class BetaContainerNetworkPolicyAllowlist` + The filename of the file cited. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `index: Integer` - An optional list of skills referenced by id or inline data. + The index of the file in the list of files. - - `class BetaSkillReference` + - `type: :file_citation` - - `skill_id: String` + The type of the file citation. Always `file_citation`. - The ID of the referenced skill. + - `:file_citation` - - `type: :skill_reference` + - `class URLCitation` - References a skill created with the /v1/skills endpoint. + A citation for a web resource used to generate a model response. - - `:skill_reference` + - `end_index: Integer` - - `version: String` + The index of the last character of the URL citation in the message. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `start_index: Integer` - - `class BetaInlineSkill` + The index of the first character of the URL citation in the message. - - `description: String` + - `title: String` - The description of the skill. + The title of the web resource. - - `name: String` + - `type: :url_citation` - The name of the skill. + The type of the URL citation. Always `url_citation`. - - `source: BetaInlineSkillSource` + - `:url_citation` - Inline skill payload + - `url: String` - - `data: String` + The URL of the web resource. - Base64-encoded skill zip bundle. + - `class ContainerFileCitation` - - `media_type: :"application/zip"` + A citation for a container file used to generate a model response. - The media type of the inline skill payload. Must be `application/zip`. + - `container_id: String` - - `:"application/zip"` + The ID of the container file. - - `type: :base64` + - `end_index: Integer` - The type of the inline skill source. Must be `base64`. + The index of the last character of the container file citation in the message. - - `:base64` + - `file_id: String` - - `type: :inline` + The ID of the file. - Defines an inline skill for this request. + - `filename: String` - - `:inline` + The filename of the container file cited. - - `class BetaLocalEnvironment` + - `start_index: Integer` - - `type: :local` + The index of the first character of the container file citation in the message. - Use a local computer environment. + - `type: :container_file_citation` - - `:local` + The type of the container file citation. Always `container_file_citation`. - - `skills: Array[BetaLocalSkill]` + - `:container_file_citation` - An optional list of skills. + - `class FilePath` - - `description: String` + A path to a file. - The description of the skill. + - `file_id: String` - - `name: String` + The ID of the file. - The name of the skill. + - `index: Integer` - - `path: String` + The index of the file in the list of files. - The path to the directory containing the skill. + - `type: :file_path` - - `class BetaContainerReference` + The type of the file path. Always `file_path`. - - `container_id: String` + - `:file_path` - The ID of the referenced container. + - `text: String` - - `type: :container_reference` + The text output from the model. - References a container created with the /v1/containers endpoint + - `type: :output_text` - - `:container_reference` + The type of the output text. Always `output_text`. - - `class BetaCustomTool` + - `: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) + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `name: String` + - `token: String` - The name of the custom tool, used to identify it in tool calls. + - `bytes: Array[Integer]` - - `type: :custom` + - `logprob: Float` - The type of the custom tool. Always `custom`. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `:custom` + - `token: String` - - `allowed_callers: Array[:direct | :programmatic]` + - `bytes: Array[Integer]` - The tool invocation context(s). + - `logprob: Float` - - `:direct` + - `class BetaResponseOutputRefusal` - - `:programmatic` + A refusal from the model. - - `defer_loading: bool` + - `refusal: String` - Whether this tool should be deferred and discovered via tool search. + The refusal explanation from the model. - - `description: String` + - `type: :refusal` - Optional description of the custom tool, used to provide more context. + The type of the refusal. Always `refusal`. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `:refusal` - The input format for the custom tool. Default is unconstrained text. + - `role: :assistant` - - `class Text` + The role of the output message. Always `assistant`. - Unconstrained free-form text. + - `:assistant` - - `type: :text` + - `status: :in_progress | :completed | :incomplete` - Unconstrained text format. Always `text`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `:text` + - `:in_progress` - - `class Grammar` + - `:completed` - A grammar defined by the user. + - `:incomplete` - - `definition: String` + - `type: :message` - The grammar definition. + The type of the output message. Always `message`. - - `syntax: :lark | :regex` + - `:message` - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent: Agent{ agent_name}` - - `:lark` + The agent that produced this item. - - `:regex` + - `agent_name: String` - - `type: :grammar` + The canonical name of the agent that produced this item. - Grammar format. Always `grammar`. + - `phase: :commentary | :final_answer` - - `:grammar` + 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. - - `class BetaNamespaceTool` + - `:commentary` - Groups function/custom tools under a shared namespace. + - `:final_answer` - - `description: String` + - `class BetaResponseFileSearchToolCall` - A description of the namespace shown to the model. + 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 namespace name used in tool calls (for example, `crm`). + The unique ID of the file search tool call. - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `queries: Array[String]` - The function/custom tools available inside this namespace. + The queries used to search for files. - - `class Function` + - `status: :in_progress | :searching | :completed | 2 more` - - `name: String` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: :function` + - `:in_progress` - - `:function` + - `:searching` - - `allowed_callers: Array[:direct | :programmatic]` + - `:completed` - The tool invocation context(s). + - `:incomplete` - - `:direct` + - `:failed` - - `:programmatic` + - `type: :file_search_call` - - `defer_loading: bool` + The type of the file search tool call. Always `file_search_call`. - Whether this function should be deferred and discovered via tool search. + - `:file_search_call` - - `description: String` + - `agent: Agent{ agent_name}` - - `output_schema: Hash[Symbol, untyped]` + 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: untyped` + The canonical name of the agent that produced this item. - - `strict: bool` + - `results: Array[Result{ attributes, file_id, filename, 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 results of the file search tool call. - - `class BetaCustomTool` + - `attributes: Hash[Symbol, String | Float | bool]` - 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) + Set of 16 key-value pairs that can be attached to an object. 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: :namespace` + - `String = String` - The type of the tool. Always `namespace`. + - `Float = Float` - - `:namespace` + - `UnionMember2 = bool` - - `class BetaToolSearchTool` + - `file_id: String` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the file. - - `type: :tool_search` + - `filename: String` - The type of the tool. Always `tool_search`. + The name of the file. - - `:tool_search` + - `score: Float` - - `description: String` + The relevance score of the file - a value between 0 and 1. - Description shown to the model for a client-executed tool search tool. + - `text: String` - - `execution: :server | :client` + The text that was retrieved from the file. - Whether tool search is executed by the server or by the client. + - `class BetaResponseComputerToolCall` - - `:server` + 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. - - `:client` + - `id: String` - - `parameters: untyped` + The unique ID of the computer call. - Parameter schema for a client-executed tool search tool. + - `call_id: String` - - `class BetaWebSearchPreviewTool` + An identifier used when responding to the tool call with 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). + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + The pending safety checks for the computer call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `id: String` - - `:web_search_preview` + The ID of the pending safety check. - - `:web_search_preview_2025_03_11` + - `code: String` - - `search_content_types: Array[:text | :image]` + The type of the pending safety check. - - `:text` + - `message: String` - - `:image` + Details about the pending safety check. - - `search_context_size: :low | :medium | :high` + - `status: :in_progress | :completed | :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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:low` + - `:in_progress` - - `:medium` + - `:completed` - - `:high` + - `:incomplete` - - `user_location: UserLocation{ type, city, country, 2 more}` + - `type: :computer_call` - The user's location. + The type of the computer call. Always `computer_call`. - - `type: :approximate` + - `:computer_call` - The type of location approximation. Always `approximate`. + - `action: BetaComputerAction` - - `:approximate` + A click action. - - `city: String` + - `class Click` - Free text input for the city of the user, e.g. `San Francisco`. + A click action. - - `country: String` + - `button: :left | :right | :wheel | 2 more` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `region: String` + - `:left` - Free text input for the region of the user, e.g. `California`. + - `:right` - - `timezone: String` + - `:wheel` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:back` - - `class BetaApplyPatchTool` + - `:forward` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: :click` - - `type: :apply_patch` + Specifies the event type. For a click action, this property is always `click`. - The type of the tool. Always `apply_patch`. + - `:click` - - `:apply_patch` + - `x: Integer` - - `allowed_callers: Array[:direct | :programmatic]` + The x-coordinate where the click occurred. - The tool invocation context(s). + - `y_: Integer` - - `:direct` + The y-coordinate where the click occurred. - - `:programmatic` + - `keys: Array[String]` - - `type: :tool_search_output` + The keys being held while clicking. - The item type. Always `tool_search_output`. + - `class DoubleClick` - - `:tool_search_output` + A double click action. - - `id: String` + - `keys: Array[String]` - The unique ID of this tool search output. + The keys being held while double-clicking. - - `agent: Agent{ agent_name}` + - `type: :double_click` - The agent that produced this item. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `agent_name: String` + - `:double_click` - The canonical name of the agent that produced this item. + - `x: Integer` - - `call_id: String` + The x-coordinate where the double click occurred. - The unique ID of the tool search call generated by the model. + - `y_: Integer` - - `execution: :server | :client` + The y-coordinate where the double click occurred. - Whether tool search was executed by the server or by the client. + - `class Drag` - - `:server` + A drag action. - - `:client` + - `path: Array[Path{ x, y_}]` - - `status: :in_progress | :completed | :incomplete` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the tool search output. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `:in_progress` + - `x: Integer` - - `:completed` + The x-coordinate. - - `:incomplete` + - `y_: Integer` - - `class AdditionalTools` + The y-coordinate. - - `role: :developer` + - `type: :drag` - The role that provided the additional tools. Only `developer` is supported. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `:developer` + - `:drag` - - `tools: Array[BetaTool]` + - `keys: Array[String]` - A list of additional tools made available at this item. + The keys being held while dragging the mouse. - - `class BetaFunctionTool` + - `class 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). + A collection of keypresses the model would like to perform. - - `class BetaFileSearchTool` + - `keys: Array[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. - - `class BetaComputerTool` + - `type: :keypress` - 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 keypress action, this property is always set to `keypress`. - - `class BetaComputerUsePreviewTool` + - `:keypress` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Move` - - `class BetaWebSearchTool` + A mouse move action. - 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: :move` - - `class Mcp` + Specifies the event type. For a move action, this property is always set to `move`. - 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). + - `:move` - - `class CodeInterpreter` + - `x: Integer` - A tool that runs Python code to help generate a response to a prompt. + The x-coordinate to move to. - - `class ProgrammaticToolCalling` + - `y_: Integer` - - `class ImageGeneration` + The y-coordinate to move to. - A tool that generates images using the GPT image models. + - `keys: Array[String]` - - `class LocalShell` + The keys being held while moving the mouse. - A tool that allows the model to execute shell commands in a local environment. + - `class Screenshot` - - `class BetaFunctionShellTool` + A screenshot action. - A tool that allows the model to execute shell commands. + - `type: :screenshot` - - `class BetaCustomTool` + Specifies the event type. For a screenshot action, this property is always set to `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) + - `:screenshot` - - `class BetaNamespaceTool` + - `class Scroll` - Groups function/custom tools under a shared namespace. + A scroll action. - - `class BetaToolSearchTool` + - `scroll_x: Integer` - Hosted or BYOT tool search configuration for deferred tools. + The horizontal scroll distance. - - `class BetaWebSearchPreviewTool` + - `scroll_y: Integer` - 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 vertical scroll distance. - - `class BetaApplyPatchTool` + - `type: :scroll` - Allows the assistant to create, delete, or update files using unified diffs. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: :additional_tools` + - `:scroll` - The item type. Always `additional_tools`. + - `x: Integer` - - `:additional_tools` + The x-coordinate where the scroll occurred. - - `id: String` + - `y_: Integer` - The unique ID of this additional tools item. + The y-coordinate where the scroll occurred. - - `agent: Agent{ agent_name}` + - `keys: Array[String]` - The agent that produced this item. + The keys being held while scrolling. - - `agent_name: String` + - `class Type` - The canonical name of the agent that produced this item. + An action to type in text. - - `class BetaResponseReasoningItem` + - `text: 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). + The text to type. - - `id: String` + - `type: :type` - The unique identifier of the reasoning content. + Specifies the event type. For a type action, this property is always set to `type`. - - `summary: Array[Summary{ text, type}]` + - `:type` - Reasoning summary content. + - `class Wait` - - `text: String` + A wait action. - A summary of the reasoning output from the model so far. + - `type: :wait` - - `type: :summary_text` + Specifies the event type. For a wait action, this property is always set to `wait`. - The type of the object. Always `summary_text`. + - `:wait` - - `:summary_text` + - `actions: BetaComputerActionList` - - `type: :reasoning` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the object. Always `reasoning`. + - `class Click` - - `:reasoning` + A click action. - - `agent: Agent{ agent_name}` + - `class DoubleClick` - The agent that produced this item. + A double click action. - - `agent_name: String` + - `class Drag` - The canonical name of the agent that produced this item. + A drag action. - - `content: Array[Content{ text, type}]` + - `class Keypress` - Reasoning text content. + A collection of keypresses the model would like to perform. - - `text: String` + - `class Move` - The reasoning text from the model. + A mouse move action. - - `type: :reasoning_text` + - `class Screenshot` - The type of the reasoning text. Always `reasoning_text`. + A screenshot action. - - `:reasoning_text` + - `class Scroll` - - `encrypted_content: String` + A scroll action. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `class Type` - - `status: :in_progress | :completed | :incomplete` + An action to type in text. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class Wait` - - `:in_progress` + A wait action. - - `:completed` + - `agent: Agent{ agent_name}` - - `:incomplete` + The agent that produced this item. - - `class BetaResponseCompactionItemParam` + - `agent_name: String` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The canonical name of the agent that produced this item. - - `encrypted_content: String` + - `class ComputerCallOutput` - The encrypted content of the compaction summary. + The output of a computer tool call. - - `type: :compaction` + - `call_id: String` - The type of the item. Always `compaction`. + The ID of the computer tool call that produced the output. - - `:compaction` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `id: String` + A computer screenshot image used with the computer use tool. - The ID of the compaction item. + - `type: :computer_screenshot` - - `agent: Agent{ 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: String` - The canonical name of the agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `class ImageGenerationCall` + - `image_url: String` - An image generation request made by the model. + The URL of the screenshot image. - - `id: String` + - `type: :computer_call_output` - The unique ID of the image generation call. + The type of the computer tool call output. Always `computer_call_output`. - - `result: String` + - `:computer_call_output` - The generated image encoded in base64. + - `id: String` - - `status: :in_progress | :completed | :generating | :failed` + The ID of the computer tool call output. - The status of the image generation call. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:in_progress` + The safety checks reported by the API that have been acknowledged by the developer. - - `:completed` + - `id: String` - - `:generating` + The ID of the pending safety check. - - `:failed` + - `code: String` - - `type: :image_generation_call` + The type of the pending safety check. - The type of the image generation call. Always `image_generation_call`. + - `message: String` - - `:image_generation_call` + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -34987,140 +45663,146 @@ Cancel a response The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` + - `status: :in_progress | :completed | :incomplete` - A tool call to run code. + 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 code interpreter tool call. + - `:completed` - - `code: String` + - `:incomplete` - The code to run, or null if not available. + - `class BetaResponseFunctionWebSearch` - - `container_id: 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 ID of the container used to run the code. + - `id: String` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + The unique ID of the web search tool call. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `class Logs` + 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 logs output from the code interpreter. + - `class Search` - - `logs: String` + Action type "search" - Performs a web search query. - The logs output from the code interpreter. + - `type: :search` - - `type: :logs` + The action type. - The type of the output. Always `logs`. + - `:search` - - `:logs` + - `queries: Array[String]` - - `class Image` + The search queries. - The image output from the code interpreter. + - `query: String` - - `type: :image` + The search query. - The type of the output. Always `image`. + - `sources: Array[Source{ type, url}]` - - `:image` + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` - `url: String` - The URL of the image output from the code interpreter. + The URL of the source. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `class OpenPage` - 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: String` - - `:failed` + The URL opened by the model. - - `type: :code_interpreter_call` + - `class FindInPage` - 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: Agent{ 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` - - `class LocalShellCall` + - `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 | :searching | :completed | :failed` - The unique ID of the local shell call. + The status of the web search tool call. - - `action: Action{ command, env, type, 3 more}` + - `:in_progress` - Execute a shell command on the server. + - `:searching` - - `command: Array[String]` + - `:completed` - The command to run. + - `:failed` - - `env: Hash[Symbol, 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: Agent{ agent_name}` - - `:exec` + The agent that produced this item. - - `timeout_ms: Integer` + - `agent_name: String` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: String` + - `class BetaResponseFunctionToolCall` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: String` + - `arguments: String` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: String` - The unique ID of the local shell tool call generated by the model. - - - `status: :in_progress | :completed | :incomplete` + The unique ID of the function tool call generated by the model. - The status of the local shell 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`. - - `type: :local_shell_call` + - `:function_call` - The type of the local shell call. Always `local_shell_call`. + - `id: String` - - `:local_shell_call` + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -35130,35 +45812,34 @@ Cancel a response The canonical name of the agent that produced this item. - - `class LocalShellCallOutput` - - The output of a local shell tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class Direct` - - `output: String` + - `type: :direct` - A JSON string of the output of the local shell tool call. + - `:direct` - - `type: :local_shell_call_output` + - `class Program` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: String` - - `:local_shell_call_output` + The call ID of the program item that produced this tool call. - - `agent: Agent{ agent_name}` + - `type: :program` - The agent that produced this item. + - `:program` - - `agent_name: String` + - `namespace: String` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -35166,147 +45847,145 @@ Cancel a response - `:incomplete` - - `class ShellCall` - - A tool representing a request to execute one or more shell commands. + - `class FunctionCallOutput` - - `action: Action{ commands, max_output_length, timeout_ms}` + The output of a function tool call. - The shell commands and limits that describe how to run the tool call. + - `call_id: String` - - `commands: Array[String]` + The unique ID of the function tool call generated by the model. - Ordered shell commands for the execution environment to run. + - `output: String | BetaResponseFunctionCallOutputItemList` - - `max_output_length: Integer` + Text, image, or file output of the function tool call. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `String = String` - - `timeout_ms: Integer` + A JSON string of the output of the function tool call. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `call_id: String` + An array of content outputs (text, image, file) for the function tool call. - The unique ID of the shell tool call generated by the model. + - `class BetaResponseInputTextContent` - - `type: :shell_call` + A text input to the model. - The type of the item. Always `shell_call`. + - `text: String` - - `:shell_call` + The text input to the model. - - `id: String` + - `type: :input_text` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the input item. Always `input_text`. - - `agent: Agent{ agent_name}` + - `:input_text` - The agent that produced this item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `agent_name: String` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: :explicit` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `:explicit` - - `class Direct` + - `class BetaResponseInputImageContent` - - `type: :direct` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The caller type. Always `direct`. + - `type: :input_image` - - `:direct` + The type of the input item. Always `input_image`. - - `class Program` + - `:input_image` - - `caller_id: String` + - `detail: :low | :high | :auto | :original` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :program` + - `:low` - The caller type. Always `program`. + - `:high` - - `:program` + - `:auto` - - `environment: BetaLocalEnvironment | BetaContainerReference` + - `:original` - The environment to execute the shell commands in. + - `file_id: String` - - `class BetaLocalEnvironment` + The ID of the file to be sent to the model. - - `class BetaContainerReference` + - `image_url: String` - - `status: :in_progress | :completed | :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 shell call. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - `class ShellCallOutput` + - `:explicit` - The streamed output items emitted by a shell tool call. + - `class BetaResponseInputFileContent` - - `call_id: String` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: :input_file` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + The type of the input item. Always `input_file`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `:input_file` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `detail: :auto | :low | :high` - The exit or timeout outcome associated with this shell 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`. - - `class Timeout` + - `:auto` - Indicates that the shell call exceeded its configured time limit. + - `:low` - - `type: :timeout` + - `:high` - The outcome type. Always `timeout`. + - `file_data: String` - - `:timeout` + The base64-encoded data of the file to be sent to the model. - - `class Exit` + - `file_id: String` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `exit_code: Integer` + - `file_url: String` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `type: :exit` + - `filename: String` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `:exit` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `stderr: 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. - Captured stderr output for the shell call. + - `mode: :explicit` - - `stdout: String` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `:explicit` - - `type: :shell_call_output` + - `type: :function_call_output` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `:shell_call_output` + - `:function_call_output` - `id: String` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -35340,13 +46019,9 @@ Cancel a response - `:program` - - `max_output_length: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `status: :in_progress | :completed | :incomplete` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -35354,85 +46029,97 @@ Cancel a response - `:incomplete` - - `class ApplyPatchCall` + - `class AgentMessage` - A tool call representing a request to create, delete, or update files using diff patches. + A message routed between agents. - - `call_id: String` + - `author: String` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class CreateFile` + - `class BetaResponseInputTextContent` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `diff: String` + - `class BetaResponseInputImageContent` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `path: String` + - `class EncryptedContent` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: :create_file` + - `encrypted_content: String` - The operation type. Always `create_file`. + Opaque encrypted content. - - `:create_file` + - `type: :encrypted_content` - - `class DeleteFile` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `:encrypted_content` - - `path: String` + - `recipient: String` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `type: :delete_file` + - `type: :agent_message` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `:delete_file` + - `:agent_message` - - `class UpdateFile` + - `id: String` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `diff: String` + - `agent: Agent{ agent_name}` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `path: String` + - `agent_name: String` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `type: :update_file` + - `class MultiAgentCall` - The operation type. Always `update_file`. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:update_file` + The multi-agent action that was executed. - - `status: :in_progress | :completed` + - `:spawn_agent` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:interrupt_agent` - - `:in_progress` + - `:list_agents` - - `:completed` + - `:send_message` - - `type: :apply_patch_call` + - `:followup_task` - The type of the item. Always `apply_patch_call`. + - `:wait_agent` - - `:apply_patch_call` + - `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: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - `agent: Agent{ agent_name}` @@ -35442,129 +46129,127 @@ Cancel a response The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. + - `class MultiAgentCallOutput` - - `class Direct` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :direct` + The multi-agent action that produced this result. - The caller type. Always `direct`. + - `:spawn_agent` - - `:direct` + - `:interrupt_agent` - - `class Program` + - `: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. - - `class ApplyPatchCallOutput` + - `output: Array[Output{ text, type, annotations}]` - The streamed output emitted by an apply patch tool call. + Text output returned by the multi-agent action. - - `call_id: String` + - `text: String` - The unique ID of the apply patch tool call generated by the model. + The text content. - - `status: :completed | :failed` + - `type: :output_text` - The status of the apply patch tool call output. One of `completed` or `failed`. + The content type. Always `output_text`. - - `:completed` + - `:output_text` - - `:failed` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `type: :apply_patch_call_output` + Citations associated with the text content. - The type of the item. Always `apply_patch_call_output`. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `:apply_patch_call_output` + - `file_id: String` - - `id: 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: Agent{ agent_name}` + The filename of the file cited. - The agent that produced this item. + - `index: Integer` - - `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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The citation type. Always `file_citation`. - The execution context that produced this tool call. + - `:file_citation` - - `class Direct` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `type: :direct` + - `end_index: Integer` - The caller type. Always `direct`. + The index of the last character of the citation in the message. - - `:direct` + - `start_index: Integer` - - `class Program` + The index of the first character of the citation in the message. - - `caller_id: String` + - `title: String` - The call ID of the program item that produced this tool call. + The title of the cited resource. - - `type: :program` + - `type: :url_citation` - The caller type. Always `program`. + The citation type. Always `url_citation`. - - `:program` + - `:url_citation` - - `output: String` + - `url: String` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The URL of the cited resource. - - `class McpListTools` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - A list of tools available on an MCP server. + - `container_id: String` - - `id: String` + The ID of the container. - The unique ID of the list. + - `end_index: Integer` - - `server_label: String` + The index of the last character of the citation in the message. - The label of the MCP server. + - `file_id: String` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + The ID of the container file. - The tools available on the server. + - `filename: String` - - `input_schema: untyped` + The filename of the container file cited. - The JSON schema describing the tool's input. + - `start_index: Integer` - - `name: String` + The index of the first character of the citation in the message. - The name of the tool. + - `type: :container_file_citation` - - `annotations: untyped` + The citation type. Always `container_file_citation`. - Additional annotations about the tool. + - `:container_file_citation` - - `description: String` + - `type: :multi_agent_call_output` - The description of the tool. + The item type. Always `multi_agent_call_output`. - - `type: :mcp_list_tools` + - `:multi_agent_call_output` - The type of the item. Always `mcp_list_tools`. + - `id: String` - - `:mcp_list_tools` + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -35574,35 +46259,21 @@ Cancel a response The canonical name of the agent that produced this item. - - `error: String` - - Error message if the server could not list tools. - - - `class McpApprovalRequest` - - 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. + - `class ToolSearchCall` - - `name: String` + - `arguments: untyped` - The name of the tool to run. + The arguments supplied to the tool search call. - - `server_label: String` + - `type: :tool_search_call` - The label of the MCP server making the request. + The item type. Always `tool_search_call`. - - `type: :mcp_approval_request` + - `:tool_search_call` - The type of the item. Always `mcp_approval_request`. + - `id: String` - - `:mcp_approval_request` + The unique ID of this tool search call. - `agent: Agent{ agent_name}` @@ -35612,1106 +46283,1137 @@ Cancel a response The canonical name of the agent that produced this item. - - `class McpApprovalResponse` + - `call_id: String` - A response to an MCP approval request. + The unique ID of the tool search call generated by the model. - - `approval_request_id: String` + - `execution: :server | :client` - The ID of the approval request being answered. + Whether tool search was executed by the server or by the client. - - `approve: bool` + - `:server` - Whether the request was approved. + - `:client` - - `type: :mcp_approval_response` + - `status: :in_progress | :completed | :incomplete` - The type of the item. Always `mcp_approval_response`. + The status of the tool search call. - - `:mcp_approval_response` + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of the approval response + - `:incomplete` - - `agent: Agent{ agent_name}` + - `class BetaResponseToolSearchOutputItemParam` - The agent that produced this item. + - `tools: Array[BetaTool]` - - `agent_name: String` + The loaded tool definitions returned by the tool search output. - The canonical name of the agent that produced this item. + - `class BetaFunctionTool` - - `reason: String` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Optional reason for the decision. + - `name: String` - - `class McpCall` + The name of the function to call. - An invocation of a tool on an MCP server. + - `parameters: Hash[Symbol, untyped]` - - `id: String` + A JSON schema object describing the parameters of the function. - The unique ID of the tool call. + - `strict: bool` - - `arguments: String` + Whether strict parameter validation is enforced for this function tool. - A JSON string of the arguments passed to the tool. + - `type: :function` - - `name: String` + The type of the function tool. Always `function`. - The name of the tool that was run. + - `:function` - - `server_label: String` + - `allowed_callers: Array[:direct | :programmatic]` - The label of the MCP server running the tool. + The tool invocation context(s). - - `type: :mcp_call` + - `:direct` - The type of the item. Always `mcp_call`. + - `:programmatic` - - `:mcp_call` + - `defer_loading: bool` - - `agent: Agent{ agent_name}` + Whether this function is deferred and loaded via tool search. - The agent that produced this item. + - `description: 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: Hash[Symbol, untyped]` - - `approval_request_id: String` + A JSON schema object describing the JSON value encoded in string outputs for this 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. + - `class BetaFileSearchTool` - - `error: 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 error from the tool call, if any. + - `type: :file_search` - - `output: String` + The type of the file search tool. Always `file_search`. - The output from the tool call. + - `:file_search` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `vector_store_ids: Array[String]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The IDs of the vector stores to search. - - `:in_progress` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `:completed` + A filter to apply. - - `:incomplete` + - `class ComparisonFilter` - - `:calling` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:failed` + - `key: String` - - `class BetaResponseCustomToolCallOutput` + The key to compare against the value. - The output of a custom tool call from your code, being sent back to the model. + - `type: :eq | :ne | :gt | 5 more` - - `call_id: String` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The call ID, used to map this custom tool call output to a custom 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 - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:eq` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `:ne` - - `String = String` + - `:gt` - A string of the output of the custom tool call. + - `:gte` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:lt` - Text, image, or file output of the custom tool call. + - `:lte` - - `class BetaResponseInputText` + - `:in` - A text input to the model. + - `:nin` - - `class BetaResponseInputImage` + - `value: String | Float | bool | Array[String | Float]` - 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. - - `class BetaResponseInputFile` + - `String = String` - A file input to the model. + - `Float = Float` - - `type: :custom_tool_call_output` + - `UnionMember2 = bool` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `UnionMember3 = Array[String | Float]` - - `:custom_tool_call_output` + - `String = String` - - `id: String` + - `Float = Float` - The unique ID of the custom tool call output in the OpenAI platform. + - `class CompoundFilter` - - `agent: Agent{ agent_name}` + Combine multiple filters using `and` or `or`. - The agent that produced this item. + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `agent_name: String` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The canonical name of the agent that produced this item. + - `class ComparisonFilter` - - `caller_: Direct{ type} | Program{ caller_id, type}` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The execution context that produced this tool call. + - `key: String` - - `class Direct` + The key to compare against the value. - - `type: :direct` + - `type: :eq | :ne | :gt | 5 more` - The caller type. Always `direct`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:direct` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class Program` + - `:eq` - - `caller_id: String` + - `:ne` - The call ID of the program item that produced this tool call. + - `:gt` - - `type: :program` + - `:gte` - The caller type. Always `program`. + - `:lt` - - `:program` + - `:lte` - - `class BetaResponseCustomToolCall` + - `:in` - A call to a custom tool created by the model. + - `:nin` - - `call_id: String` + - `value: String | Float | bool | Array[String | Float]` - An identifier used to map this custom tool call to a tool call output. + The value to compare against the attribute key; supports string, number, or boolean types. - - `input: String` + - `String = String` - The input for the custom tool call generated by the model. + - `Float = Float` - - `name: String` + - `UnionMember2 = bool` - The name of the custom tool being called. + - `UnionMember3 = Array[String | Float]` - - `type: :custom_tool_call` + - `String = String` - The type of the custom tool call. Always `custom_tool_call`. + - `Float = Float` - - `:custom_tool_call` + - `UnionMember1 = untyped` - - `id: String` + - `type: :and | :or` - The unique ID of the custom tool call in the OpenAI platform. + Type of operation: `and` or `or`. - - `agent: Agent{ agent_name}` + - `:and` - The agent that produced this item. + - `:or` - - `agent_name: String` + - `max_num_results: Integer` - The canonical name of the agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The execution context that produced this tool call. + Ranking options for search. - - `class Direct` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `type: :direct` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `:direct` + - `embedding_weight: Float` - - `class Program` + The weight of the embedding in the reciprocal ranking fusion. - - `caller_id: String` + - `text_weight: Float` - The call ID of the program item that produced this tool call. + The weight of the text in the reciprocal ranking fusion. - - `type: :program` + - `ranker: :auto | :"default-2024-11-15"` - - `:program` + The ranker to use for the file search. - - `namespace: String` + - `:auto` - The namespace of the custom tool being called. + - `:"default-2024-11-15"` - - `class CompactionTrigger` + - `score_threshold: Float` - Compacts the current context. Must be the final input 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. - - `type: :compaction_trigger` + - `class BetaComputerTool` - The type of the item. Always `compaction_trigger`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:compaction_trigger` + - `type: :computer` - - `agent: Agent{ agent_name}` + The type of the computer tool. Always `computer`. - The agent that produced this item. + - `:computer` - - `agent_name: String` + - `class BetaComputerUsePreviewTool` - 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). - - `class ItemReference` + - `display_height: Integer` - An internal identifier for an item to reference. + The height of the computer display. - - `id: String` + - `display_width: Integer` - The ID of the item to reference. + The width of the computer display. - - `agent: Agent{ agent_name}` + - `environment: :windows | :mac | :linux | 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` - - `type: :item_reference` + - `:linux` - The type of item to reference. Always `item_reference`. + - `:ubuntu` - - `:item_reference` + - `:browser` - - `class Program` + - `type: :computer_use_preview` - - `id: String` + The type of the computer use tool. Always `computer_use_preview`. - The unique ID of this program item. + - `:computer_use_preview` - - `call_id: String` + - `class BetaWebSearchTool` - The stable call ID of the program 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). - - `code: String` + - `type: :web_search | :web_search_2025_08_26` - The JavaScript source executed by programmatic tool calling. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `fingerprint: String` + - `:web_search` - Opaque program replay fingerprint that must be round-tripped. + - `:web_search_2025_08_26` - - `type: :program` + - `filters: Filters{ allowed_domains}` - The item type. Always `program`. + Filters for the search. - - `:program` + - `allowed_domains: Array[String]` - - `agent: Agent{ 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: :low | :medium | :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. - - `class ProgramOutput` + - `:low` - - `id: String` + - `:medium` - The unique ID of this program output item. + - `:high` - - `call_id: String` + - `user_location: UserLocation{ city, country, region, 2 more}` - The call ID of the program item. + The approximate location of the user. - - `result: String` + - `city: String` - The result produced by the program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: :completed | :incomplete` + - `country: String` - The terminal status of the program output. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `:completed` + - `region: String` - - `:incomplete` + Free text input for the region of the user, e.g. `California`. - - `type: :program_output` + - `timezone: String` - The item type. Always `program_output`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:program_output` + - `type: :approximate` - - `agent: Agent{ agent_name}` + The type of location approximation. Always `approximate`. - The agent that produced this item. + - `:approximate` - - `agent_name: String` + - `class Mcp` - The canonical name of the agent that produced this item. + 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). - - `metadata: Hash[Symbol, String]` + - `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` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + The type of the MCP tool. Always `mcp`. - 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` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `allowed_callers: Array[:direct | :programmatic]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The tool invocation context(s). - - `:"gpt-5.6-sol"` + - `:direct` - - `:"gpt-5.6-terra"` + - `:programmatic` - - `:"gpt-5.6-luna"` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `:"gpt-5.4"` + List of allowed tool names or a filter object. - - `:"gpt-5.4-mini"` + - `McpAllowedTools = Array[String]` - - `:"gpt-5.4-nano"` + A string array of allowed tool names - - `:"gpt-5.4-mini-2026-03-17"` + - `class McpToolFilter` - - `:"gpt-5.4-nano-2026-03-17"` + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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.3-chat-latest"` + - `tool_names: Array[String]` - - `:"gpt-5.2"` + List of allowed tool names. - - `:"gpt-5.2-2025-12-11"` + - `authorization: String` - - `:"gpt-5.2-chat-latest"` + 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.2-pro"` + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `:"gpt-5.2-pro-2025-12-11"` + 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.1"` + Currently supported `connector_id` values are: - - `:"gpt-5.1-2025-11-13"` + - 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.1-codex"` + - `:connector_dropbox` - - `:"gpt-5.1-mini"` + - `:connector_gmail` - - `:"gpt-5.1-chat-latest"` + - `:connector_googlecalendar` - - `:"gpt-5"` + - `:connector_googledrive` - - `:"gpt-5-mini"` + - `:connector_microsoftteams` - - `:"gpt-5-nano"` + - `:connector_outlookcalendar` - - `:"gpt-5-2025-08-07"` + - `:connector_outlookemail` - - `:"gpt-5-mini-2025-08-07"` + - `:connector_sharepoint` - - `:"gpt-5-nano-2025-08-07"` + - `defer_loading: bool` - - `:"gpt-5-chat-latest"` + Whether this MCP tool is deferred and discovered via tool search. - - `:"gpt-4.1"` + - `headers: Hash[Symbol, String]` - - `:"gpt-4.1-mini"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `:"gpt-4.1-nano"` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `:"gpt-4.1-2025-04-14"` + Specify which of the MCP server's tools require approval. - - `:"gpt-4.1-mini-2025-04-14"` + - `class McpToolApprovalFilter` - - `:"gpt-4.1-nano-2025-04-14"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `:"o4-mini"` + - `always: Always{ read_only, tool_names}` - - `:"o4-mini-2025-04-16"` + A filter object to specify which tools are allowed. - - `:o3` + - `read_only: bool` - - `:"o3-2025-04-16"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:"o3-mini"` + - `tool_names: Array[String]` - - `:"o3-mini-2025-01-31"` + List of allowed tool names. - - `:o1` + - `never: Never{ read_only, tool_names}` - - `:"o1-2024-12-17"` + A filter object to specify which tools are allowed. - - `:"o1-preview"` + - `read_only: bool` - - `:"o1-preview-2024-09-12"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:"o1-mini"` + - `tool_names: Array[String]` - - `:"o1-mini-2024-09-12"` + List of allowed tool names. - - `:"gpt-4o"` + - `McpToolApprovalSetting = :always | :never` - - `:"gpt-4o-2024-11-20"` + 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-2024-08-06"` + - `:always` - - `:"gpt-4o-2024-05-13"` + - `:never` - - `:"gpt-4o-audio-preview"` + - `server_description: String` - - `:"gpt-4o-audio-preview-2024-10-01"` + Optional description of the MCP server, used to provide more context. - - `:"gpt-4o-audio-preview-2024-12-17"` + - `server_url: String` - - `:"gpt-4o-audio-preview-2025-06-03"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:"gpt-4o-mini-audio-preview"` + - `tunnel_id: String` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `:"gpt-4o-search-preview"` + - `class CodeInterpreter` - - `:"gpt-4o-mini-search-preview"` + A tool that runs Python code to help generate a response to a prompt. - - `:"gpt-4o-search-preview-2025-03-11"` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + 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. - - `:"chatgpt-4o-latest"` + - `String = String` - - `:"codex-mini-latest"` + The container ID. - - `:"gpt-4o-mini"` + - `class CodeInterpreterToolAuto` - - `:"gpt-4o-mini-2024-07-18"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `:"gpt-4-turbo"` + - `type: :auto` - - `:"gpt-4-turbo-2024-04-09"` + Always `auto`. - - `:"gpt-4-0125-preview"` + - `:auto` - - `:"gpt-4-turbo-preview"` + - `file_ids: Array[String]` - - `:"gpt-4-1106-preview"` + An optional list of uploaded files to make available to your code. - - `:"gpt-4-vision-preview"` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:"gpt-4"` + The memory limit for the code interpreter container. - - `:"gpt-4-0314"` + - `:"1g"` - - `:"gpt-4-0613"` + - `:"4g"` - - `:"gpt-4-32k"` + - `:"16g"` - - `:"gpt-4-32k-0314"` + - `:"64g"` - - `:"gpt-4-32k-0613"` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:"gpt-3.5-turbo"` + Network access policy for the container. - - `:"gpt-3.5-turbo-16k"` + - `class BetaContainerNetworkPolicyDisabled` - - `:"gpt-3.5-turbo-0301"` + - `type: :disabled` - - `:"gpt-3.5-turbo-0613"` + Disable outbound network access. Always `disabled`. - - `:"gpt-3.5-turbo-1106"` + - `:disabled` - - `:"gpt-3.5-turbo-0125"` + - `class BetaContainerNetworkPolicyAllowlist` - - `:"gpt-3.5-turbo-16k-0613"` + - `allowed_domains: Array[String]` - - `:"o1-pro"` + A list of allowed domains when type is `allowlist`. - - `:"o1-pro-2025-03-19"` + - `type: :allowlist` - - `:"o3-pro"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `:"o3-pro-2025-06-10"` + - `:allowlist` - - `:"o3-deep-research"` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `:"o3-deep-research-2025-06-26"` + Optional domain-scoped secrets for allowlisted domains. - - `:"o4-mini-deep-research"` + - `domain: String` - - `:"o4-mini-deep-research-2025-06-26"` + The domain associated with the secret. - - `:"computer-use-preview"` + - `name: String` - - `:"computer-use-preview-2025-03-11"` + The name of the secret to inject for the domain. - - `:"gpt-5-codex"` + - `value: String` - - `:"gpt-5-pro"` + The secret value to inject for the domain. - - `:"gpt-5-pro-2025-10-06"` + - `type: :code_interpreter` - - `:"gpt-5.1-codex-max"` + The type of the code interpreter tool. Always `code_interpreter`. - - `String = String` + - `:code_interpreter` - - `object: :response` + - `allowed_callers: Array[:direct | :programmatic]` - The object type of this resource - always set to `response`. + The tool invocation context(s). - - `:response` + - `:direct` - - `output: Array[BetaResponseOutputItem]` + - `:programmatic` - An array of content items generated by the model. + - `class ProgrammaticToolCalling` - - 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. + - `type: :programmatic_tool_calling` - - `class BetaResponseOutputMessage` + The type of the tool. Always `programmatic_tool_calling`. - An output message from the model. + - `:programmatic_tool_calling` - - `class BetaResponseFileSearchToolCall` + - `class ImageGeneration` - 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 tool that generates images using the GPT image models. - - `class BetaResponseFunctionToolCall` + - `type: :image_generation` - 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 the image generation tool. Always `image_generation`. - - `class BetaResponseFunctionToolCallOutputItem` + - `:image_generation` - - `id: String` + - `action: :generate | :edit | :auto` - The unique ID of the function call tool output. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `call_id: String` + - `:generate` - The unique ID of the function tool call generated by the model. + - `:edit` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:auto` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `background: :transparent | :opaque | :auto` - - `String = 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. - A string of the output of the function 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. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - Text, image, or file output of the function call. + - `:transparent` - - `class BetaResponseInputText` + - `:opaque` - A text input to the model. + - `:auto` - - `class BetaResponseInputImage` + - `input_fidelity: :high | :low` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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`. - - `class BetaResponseInputFile` + - `:high` - A file input to the model. + - `:low` - - `status: :in_progress | :completed | :incomplete` + - `input_image_mask: InputImageMask{ file_id, image_url}` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `:in_progress` + - `file_id: String` - - `:completed` + File ID for the mask image. - - `:incomplete` + - `image_url: String` - - `type: :function_call_output` + Base64-encoded mask image. - The type of the function tool call output. Always `function_call_output`. + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:function_call_output` + The image generation model to use. Default: `gpt-image-1`. - - `agent: Agent{ agent_name}` + - `String = String` - The agent that produced this item. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. + - `:"gpt-image-1"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-image-1-mini"` - The execution context that produced this tool call. + - `:"gpt-image-2"` - - `class Direct` + - `:"gpt-image-2-2026-04-21"` - - `type: :direct` + - `:"gpt-image-1.5"` - The caller type. Always `direct`. + - `:"chatgpt-image-latest"` - - `:direct` + - `moderation: :auto | :low` - - `class Program` + Moderation level for the generated image. Default: `auto`. - - `caller_id: String` + - `:auto` - The call ID of the program item that produced this tool call. + - `:low` - - `type: :program` + - `output_compression: Integer` - The caller type. Always `program`. + Compression level for the output image. Default: 100. - - `:program` + - `output_format: :png | :webp | :jpeg` - - `created_by: String` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of the actor that created the item. + - `:png` - - `class AgentMessage` + - `:webp` - - `id: String` + - `:jpeg` - The unique ID of the agent message. + - `partial_images: Integer` - - `author: String` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The sending agent identity. + - `quality: :low | :medium | :high | :auto` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Encrypted content sent between agents. + - `:low` - - `class BetaResponseInputText` + - `:medium` - A text input to the model. + - `:high` - - `class BetaResponseOutputText` + - `:auto` - A text output from the model. + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `class 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`. - A text content. + - `String = String` - - `text: String` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `type: :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`. - - `:text` + - `:"1024x1024"` - - `class SummaryText` + - `:"1024x1536"` - A summary text from the model. + - `:"1536x1024"` - - `text: String` + - `:auto` - A summary of the reasoning output from the model so far. + - `class LocalShell` - - `type: :summary_text` + A tool that allows the model to execute shell commands in a local environment. - The type of the object. Always `summary_text`. + - `type: :local_shell` - - `:summary_text` + The type of the local shell tool. Always `local_shell`. - - `class ReasoningText` + - `:local_shell` - Reasoning text from the model. + - `class BetaFunctionShellTool` - - `text: String` + A tool that allows the model to execute shell commands. - The reasoning text from the model. + - `type: :shell` - - `type: :reasoning_text` + The type of the shell tool. Always `shell`. - The type of the reasoning text. Always `reasoning_text`. + - `:shell` - - `:reasoning_text` + - `allowed_callers: Array[:direct | :programmatic]` - - `class BetaResponseOutputRefusal` + The tool invocation context(s). - A refusal from the model. + - `:direct` - - `class BetaResponseInputImage` + - `:programmatic` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `class ComputerScreenshot` + - `class BetaContainerAuto` - A screenshot of a computer. + - `type: :container_auto` - - `detail: :low | :high | :auto | :original` + Automatically creates a container for this request - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:container_auto` - - `:low` + - `file_ids: Array[String]` - - `:high` + An optional list of uploaded files to make available to your code. - - `:auto` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:original` + The memory limit for the container. - - `file_id: String` + - `:"1g"` - The identifier of an uploaded file that contains the screenshot. + - `:"4g"` - - `image_url: String` + - `:"16g"` - The URL of the screenshot image. + - `:"64g"` - - `type: :computer_screenshot` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Network access policy for the container. - - `:computer_screenshot` + - `class BetaContainerNetworkPolicyDisabled` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class 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. + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `mode: :explicit` + An optional list of skills referenced by id or inline data. - The breakpoint mode. Always `explicit`. + - `class BetaSkillReference` - - `:explicit` + - `skill_id: String` - - `class BetaResponseInputFile` + The ID of the referenced skill. - A file input to the model. + - `type: :skill_reference` - - `class EncryptedContent` + References a skill created with the /v1/skills endpoint. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `:skill_reference` - - `encrypted_content: String` + - `version: String` - Opaque encrypted content. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: :encrypted_content` + - `class BetaInlineSkill` - The type of the input item. Always `encrypted_content`. + - `description: String` - - `:encrypted_content` + The description of the skill. - - `recipient: String` + - `name: String` - The destination agent identity. + The name of the skill. - - `type: :agent_message` + - `source: BetaInlineSkillSource` - The type of the item. Always `agent_message`. + Inline skill payload - - `:agent_message` + - `data: String` - - `agent: Agent{ 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"` - - `class MultiAgentCall` + - `type: :base64` - - `id: String` + The type of the inline skill source. Must be `base64`. - The unique ID of the multi-agent call item. + - `:base64` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :inline` - The multi-agent action to execute. + Defines an inline skill for this request. - - `:spawn_agent` + - `:inline` - - `:interrupt_agent` + - `class BetaLocalEnvironment` - - `:list_agents` + - `type: :local` - - `:send_message` + Use a local computer environment. - - `:followup_task` + - `:local` - - `:wait_agent` + - `skills: Array[BetaLocalSkill]` - - `arguments: String` + An optional list of skills. - The JSON string of arguments generated for the action. + - `description: String` - - `call_id: String` + The description of the skill. - The unique ID linking this call to its output. + - `name: String` - - `type: :multi_agent_call` + The name of the skill. - The type of the multi-agent call. Always `multi_agent_call`. + - `path: String` - - `:multi_agent_call` + The path to the directory containing the skill. - - `agent: Agent{ agent_name}` + - `class BetaContainerReference` - The agent that produced this item. + - `container_id: String` - - `agent_name: String` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: :container_reference` - - `class MultiAgentCallOutput` + References a container created with the /v1/containers endpoint - - `id: String` + - `:container_reference` - The unique ID of the multi-agent call output item. + - `class BetaCustomTool` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 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 produced this result. + - `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: Array[:direct | :programmatic]` - - `:wait_agent` + The tool invocation context(s). - - `call_id: String` + - `:direct` - The unique ID of the multi-agent call. + - `:programmatic` - - `output: Array[BetaResponseOutputText]` + - `defer_loading: bool` - Text output returned by the multi-agent action. + Whether this tool should be deferred and discovered via tool search. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `description: String` - The annotations of the text output. + Optional description of the custom tool, used to provide more context. - - `text: String` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - The text output from the model. + The input format for the custom tool. Default is unconstrained text. - - `type: :output_text` + - `class Text` - The type of the output text. Always `output_text`. + Unconstrained free-form text. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `type: :text` - - `type: :multi_agent_call_output` + Unconstrained text format. Always `text`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `:text` - - `:multi_agent_call_output` + - `class Grammar` - - `agent: Agent{ 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 | :regex` - - `class BetaResponseFunctionWebSearch` + The syntax of the grammar definition. One of `lark` or `regex`. - 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. + - `:lark` - - `class BetaResponseComputerToolCall` + - `:regex` - 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: :grammar` - - `class BetaResponseComputerToolCallOutputItem` + Grammar format. Always `grammar`. - - `id: String` + - `:grammar` - The unique ID of the computer call tool output. + - `class BetaNamespaceTool` - - `call_id: String` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call that produced the output. + - `description: String` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A description of the namespace shown to the model. - A computer screenshot image used with the computer use tool. + - `name: String` - - `status: :completed | :incomplete | :failed | :in_progress` + The namespace name used in tool calls (for example, `crm`). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `:completed` + The function/custom tools available inside this namespace. - - `:incomplete` + - `class Function` - - `:failed` + - `name: String` - - `:in_progress` + - `type: :function` - - `type: :computer_call_output` + - `:function` - The type of the computer tool call output. Always `computer_call_output`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:computer_call_output` + The tool invocation context(s). - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `:direct` - The safety checks reported by the API that have been acknowledged by the - developer. + - `:programmatic` - - `id: String` + - `defer_loading: bool` - The ID of the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `code: String` + - `description: String` - The type of the pending safety check. + - `output_schema: Hash[Symbol, untyped]` - - `message: String` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Details about the pending safety check. + - `parameters: untyped` - - `agent: Agent{ agent_name}` + - `strict: bool` - The agent that produced this item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `agent_name: String` + - `class BetaCustomTool` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `created_by: String` + - `type: :namespace` - The identifier of the actor that created the item. + The type of the tool. Always `namespace`. - - `class BetaResponseReasoningItem` + - `:namespace` - 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). + - `class BetaToolSearchTool` - - `class Program` + 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: String` - - `code: String` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `execution: :server | :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: untyped` - - `:program` + Parameter schema for a client-executed tool search tool. - - `agent: Agent{ agent_name}` + - `class BetaWebSearchPreviewTool` - 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 | :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`. - - `class ProgramOutput` + - `:web_search_preview` - - `id: String` + - `:web_search_preview_2025_03_11` - The unique ID of the program output item. + - `search_content_types: Array[:text | :image]` - - `call_id: String` + - `:text` - The call ID of the program item. + - `:image` - - `result: String` + - `search_context_size: :low | :medium | :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 | :incomplete` + - `:low` - The terminal status of the program output item. + - `:medium` - - `:completed` + - `:high` - - `:incomplete` + - `user_location: UserLocation{ 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: Agent{ agent_name}` + - `:approximate` - The agent that produced this item. + - `city: 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: String` - - `class BetaResponseToolSearchCall` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `id: String` + - `region: String` - The unique ID of the tool search call item. + Free text input for the region of the user, e.g. `California`. - - `arguments: untyped` + - `timezone: 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` + - `class BetaApplyPatchTool` - 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 | :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: Array[:direct | :programmatic]` - - `status: :in_progress | :completed | :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: String` - - `:tool_search_call` + The unique ID of this tool search output. - `agent: Agent{ agent_name}` @@ -36721,16 +47423,6 @@ Cancel a response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem` - - - `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. @@ -36745,7 +47437,7 @@ Cancel a response - `status: :in_progress | :completed | :incomplete` - The status of the tool search output item that was recorded. + The status of the tool search output. - `:in_progress` @@ -36753,9 +47445,17 @@ Cancel a response - `:incomplete` + - `class AdditionalTools` + + - `role: :developer` + + The role that provided the additional tools. Only `developer` is supported. + + - `:developer` + - `tools: Array[BetaTool]` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `class BetaFunctionTool` @@ -36821,11 +47521,15 @@ Cancel a response Allows the assistant to create, delete, or update files using unified diffs. - - `type: :tool_search_output` + - `type: :additional_tools` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `:tool_search_output` + - `:additional_tools` + + - `id: String` + + The unique ID of this additional tools item. - `agent: Agent{ agent_name}` @@ -36835,109 +47539,130 @@ Cancel a response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningItem` - - `class AdditionalTools` + 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 ID of the additional tools item. + The unique identifier of the reasoning content. - - `role: :unknown | :user | :assistant | 5 more` + - `summary: Array[Summary{ text, type}]` - The role that provided the additional tools. + Reasoning summary content. - - `:unknown` + - `text: String` - - `:user` + A summary of the reasoning output from the model so far. - - `:assistant` + - `type: :summary_text` - - `:system` + The type of the object. Always `summary_text`. - - `:critic` + - `:summary_text` - - `:discriminator` + - `type: :reasoning` - - `:developer` + The type of the object. Always `reasoning`. - - `:tool` + - `:reasoning` - - `tools: Array[BetaTool]` + - `agent: Agent{ agent_name}` - The additional tool definitions made available at this item. + The agent that produced this item. - - `class BetaFunctionTool` + - `agent_name: String` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool` + - `content: Array[Content{ text, 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). + Reasoning text content. - - `class BetaComputerTool` + - `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 reasoning text from the model. - - `class BetaComputerUsePreviewTool` + - `type: :reasoning_text` - 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 reasoning text. Always `reasoning_text`. - - `class BetaWebSearchTool` + - `: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). + - `encrypted_content: String` - - `class Mcp` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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). + - `status: :in_progress | :completed | :incomplete` - - `class CodeInterpreter` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool that runs Python code to help generate a response to a prompt. + - `:in_progress` - - `class ProgrammaticToolCalling` + - `:completed` - - `class ImageGeneration` + - `:incomplete` - A tool that generates images using the GPT image models. + - `class BetaResponseCompactionItemParam` - - `class LocalShell` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A tool that allows the model to execute shell commands in a local environment. + - `encrypted_content: String` - - `class BetaFunctionShellTool` + The encrypted content of the compaction summary. - A tool that allows the model to execute shell commands. + - `type: :compaction` - - `class BetaCustomTool` + The type of the item. Always `compaction`. - 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) + - `:compaction` - - `class BetaNamespaceTool` + - `id: String` - Groups function/custom tools under a shared namespace. + The ID of the compaction item. - - `class BetaToolSearchTool` + - `agent: Agent{ agent_name}` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `class BetaWebSearchPreviewTool` + - `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. - - `class BetaApplyPatchTool` + - `class ImageGenerationCall` - Allows the assistant to create, delete, or update files using unified diffs. + An image generation request made by the model. - - `type: :additional_tools` + - `id: String` - The type of the item. Always `additional_tools`. + The unique ID of the image generation call. - - `:additional_tools` + - `result: String` + + The generated image encoded in base64. + + - `status: :in_progress | :completed | :generating | :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: Agent{ agent_name}` @@ -36947,65 +47672,74 @@ Cancel a response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` + - `class BetaResponseCodeInterpreterToolCall` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A tool call to run code. - `id: String` - The unique ID of the compaction item. + The unique ID of the code interpreter tool call. - - `encrypted_content: String` + - `code: String` - The encrypted content that was produced by compaction. + The code to run, or null if not available. - - `type: :compaction` + - `container_id: String` - The type of the item. Always `compaction`. + The ID of the container used to run the code. - - `:compaction` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `agent: Agent{ agent_name}` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The agent that produced this item. + - `class Logs` - - `agent_name: String` + The logs output from the code interpreter. - The canonical name of the agent that produced this item. + - `logs: String` - - `created_by: String` + The logs output from the code interpreter. - The identifier of the actor that created the item. + - `type: :logs` - - `class ImageGenerationCall` + The type of the output. Always `logs`. - An image generation request made by the model. + - `:logs` - - `id: String` + - `class Image` - The unique ID of the image generation call. + The image output from the code interpreter. - - `result: String` + - `type: :image` - The generated image encoded in base64. + The type of the output. Always `image`. - - `status: :in_progress | :completed | :generating | :failed` + - `:image` - The status of the image generation call. + - `url: String` + + The URL of the image output from the code interpreter. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `:in_progress` - `:completed` - - `:generating` + - `:incomplete` + + - `:interpreting` - `:failed` - - `type: :image_generation_call` + - `type: :code_interpreter_call` - The type of the image generation call. Always `image_generation_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `:image_generation_call` + - `:code_interpreter_call` - `agent: Agent{ agent_name}` @@ -37015,10 +47749,6 @@ Cancel a response The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` - - A tool call to run code. - - `class LocalShellCall` A tool call to run a command on the local shell. @@ -37119,69 +47849,31 @@ Cancel a response - `:completed` - - `:incomplete` - - - `class BetaResponseFunctionShellToolCall` - - 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: Action{ commands, max_output_length, timeout_ms}` - - The shell commands and limits that describe how to run the tool call. - - - `commands: Array[String]` - - - `max_output_length: Integer` - - Optional maximum number of characters to return from each command. - - - `timeout_ms: Integer` - - Optional timeout in milliseconds for the commands. - - - `call_id: String` - - The unique ID of the shell tool call generated by the model. - - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. + - `:incomplete` - - `:local` + - `class ShellCall` - - `class BetaResponseContainerReference` + A tool representing a request to execute one or more shell commands. - Represents a container created with /v1/containers. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `container_id: String` + The shell commands and limits that describe how to run the tool call. - - `type: :container_reference` + - `commands: Array[String]` - The environment type. Always `container_reference`. + Ordered shell commands for the execution environment to run. - - `:container_reference` + - `max_output_length: Integer` - - `status: :in_progress | :completed | :incomplete` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `timeout_ms: Integer` - - `:in_progress` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `:completed` + - `call_id: String` - - `:incomplete` + The unique ID of the shell tool call generated by the model. - `type: :shell_call` @@ -37189,6 +47881,10 @@ Cancel a response - `:shell_call` + - `id: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -37205,6 +47901,8 @@ Cancel a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -37215,35 +47913,43 @@ Cancel a response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `environment: BetaLocalEnvironment | BetaContainerReference` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput` + - `class BetaLocalEnvironment` - The output of a shell tool call that was emitted. + - `class BetaContainerReference` - - `id: String` + - `status: :in_progress | :completed | :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: Integer` + - `:incomplete` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput` - - `output: Array[Output{ 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[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Timeout{ type} | Exit{ 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. - `class Timeout` @@ -37261,7 +47967,7 @@ Cancel a response - `exit_code: Integer` - Exit code from the shell process. + The exit code returned by the shell process. - `type: :exit` @@ -37271,32 +47977,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: String` - - The identifier of the actor that created the item. - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -37313,6 +48009,8 @@ Cancel a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -37323,19 +48021,27 @@ Cancel a response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `max_output_length: Integer` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall` + - `status: :in_progress | :completed | :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` + + - `class ApplyPatchCall` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: String` @@ -37343,55 +48049,55 @@ Cancel a response - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ 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. - `class CreateFile` - 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` - `class DeleteFile` - 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` - `class UpdateFile` - 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` @@ -37409,6 +48115,10 @@ Cancel a response - `:apply_patch_call` + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -37425,6 +48135,8 @@ Cancel a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -37435,19 +48147,13 @@ Cancel a response - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `:program` - - `id: String` + - `class ApplyPatchCallOutput` - 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` @@ -37467,6 +48173,10 @@ Cancel a response - `:apply_patch_call_output` + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -37483,6 +48193,8 @@ Cancel a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -37493,76 +48205,13 @@ Cancel a response - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call output. - - - `output: String` - - Optional textual output returned by the apply patch tool. - - - `class McpCall` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `approval_request_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. - - - `error: String` + The caller type. Always `program`. - The error from the tool call, if any. + - `:program` - `output: String` - The output from the tool call. - - - `status: :in_progress | :completed | :incomplete | 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). - `class McpListTools` @@ -37652,10 +48301,6 @@ Cancel a response 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. @@ -37670,6 +48315,10 @@ Cancel a response - `:mcp_approval_response` + - `id: String` + + The unique ID of the approval response + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -37682,469 +48331,87 @@ Cancel a response Optional reason for the decision. - - `class BetaResponseCustomToolCall` - - A call to a custom tool created by the model. - - - `class BetaResponseCustomToolCallOutputItem` + - `class McpCall` - The output of a custom tool call from your code, being sent back to the model. + An invocation of a tool on an MCP server. - `id: String` - The unique ID of the custom tool call output item. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `parallel_tool_calls: bool` - - Whether to allow the model to run tool calls in parallel. - - - `temperature: Float` - - 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 | BetaToolChoiceAllowed | BetaToolChoiceTypes | 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 | :auto | :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` - - - `class BetaToolChoiceAllowed` - - Constrains the tools available to the model to a pre-defined set. - - - `mode: :auto | :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[Hash[Symbol, untyped]]` - - 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` - - - `class BetaToolChoiceTypes` - - 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 | :web_search_preview | :computer | 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` + The unique ID of the tool call. - - `class BetaToolChoiceFunction` + - `arguments: String` - Use this option to force the model to call a specific function. + A JSON string of the arguments passed to the tool. - `name: String` - The name of the function to call. - - - `type: :function` - - For function calling, the type is always `function`. - - - `:function` - - - `class BetaToolChoiceMcp` - - Use this option to force the model to call a specific tool on a remote MCP server. + The name of the tool that was run. - `server_label: String` - The label of the MCP server to use. - - - `type: :mcp` - - For MCP tools, the type is always `mcp`. - - - `:mcp` - - - `name: String` - - The name of the tool to call on the server. - - - `class BetaToolChoiceCustom` - - 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` - - - `class BetaSpecificProgrammaticToolCallingParam` - - - `type: :programmatic_tool_calling` - - The tool to call. Always `programmatic_tool_calling`. - - - `:programmatic_tool_calling` - - - `class BetaToolChoiceApplyPatch` - - 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` - - - `class BetaToolChoiceShell` - - 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[BetaTool]` - - 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. - - - `class BetaFunctionTool` - - 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). - - - `class BetaFileSearchTool` - - 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). - - - `class BetaComputerTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool` - - 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). - - - `class Mcp` - - 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). - - - `class CodeInterpreter` - - A tool that runs Python code to help generate a response to a prompt. - - - `class ProgrammaticToolCalling` - - - `class ImageGeneration` - - A tool that generates images using the GPT image models. - - - `class LocalShell` - - A tool that allows the model to execute shell commands in a local environment. - - - `class BetaFunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool` - - 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) - - - `class BetaNamespaceTool` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool` - - 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). - - - `class BetaApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `top_p: Float` - - 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: bool` - - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). - - - `completed_at: Float` - - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. - - - `conversation: Conversation{ 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: Integer` - - 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: Integer` - - 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: Moderation{ input, output}` - - Moderation results for the response input and output, if moderated completions were requested. - - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - Moderation for the response input. - - - `class ModerationResult` - - A moderation result produced for the response input or output. - - - `categories: Hash[Symbol, bool]` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - Which modalities of input are reflected by the score for each category. - - - `:text` - - - `:image` - - - `category_scores: Hash[Symbol, Float]` - - A dictionary of moderation categories to scores. - - - `flagged: bool` - - 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` - - - `class Error` - - 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: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - Moderation for the response output. - - - `class ModerationResult` - - A moderation result produced for the response input or output. - - - `categories: Hash[Symbol, bool]` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The label of the MCP server running the tool. - Which modalities of input are reflected by the score for each category. + - `type: :mcp_call` - - `:text` + The type of the item. Always `mcp_call`. - - `:image` + - `:mcp_call` - - `category_scores: Hash[Symbol, Float]` + - `agent: Agent{ agent_name}` - A dictionary of moderation categories to scores. + The agent that produced this item. - - `flagged: bool` + - `agent_name: String` - A boolean indicating whether the content was flagged by any category. + The canonical name of the agent that produced this item. - - `model: String` + - `approval_request_id: String` - The moderation model that produced this result. + 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: :moderation_result` + - `error: String` - The object type, which was always `moderation_result` for successful moderation results. + The error from the tool call, if any. - - `:moderation_result` + - `output: String` - - `class Error` + The output from the tool call. - An error produced while attempting moderation for the response input or output. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `code: String` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The error code. + - `:in_progress` - - `message: String` + - `:completed` - The error message. + - `:incomplete` - - `type: :error` + - `:calling` - The object type, which was always `error` for moderation failures. + - `:failed` - - `:error` + - `class BetaResponseCustomToolCallOutput` - - `previous_response_id: String` + The output of a custom tool call from your code, being sent back to the model. - 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`. + - `call_id: String` - - `prompt: BetaResponsePrompt` + The call ID, used to map this custom tool call output to a custom tool call. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `id: String` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The unique identifier of the prompt template to use. + - `String = String` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + A string of the output of the custom tool call. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `String = String` + Text, image, or file output of the custom tool call. - `class BetaResponseInputText` @@ -38158,545 +48425,236 @@ Cancel a response A file input to the model. - - `version: String` - - Optional version of the prompt template. - - - `prompt_cache_key: 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: PromptCacheOptions{ mode, ttl}` - - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - - `mode: :implicit | :explicit` - - Whether implicit prompt-cache breakpoints were enabled. - - - `:implicit` - - - `:explicit` - - - `ttl: :"30m"` - - The minimum lifetime applied to each cache breakpoint. - - - `:"30m"` - - - `prompt_cache_retention: :in_memory | :"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: Reasoning{ 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: :auto | :current_turn | :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: :none | :minimal | :low | 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: :auto | :concise | :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: String | :standard | :pro` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `String = String` + - `type: :custom_tool_call_output` - - `Mode = :standard | :pro` + The type of the custom tool call output. Always `custom_tool_call_output`. - Controls the reasoning execution mode for the request. + - `:custom_tool_call_output` - When returned on a response, this is the effective execution mode. + - `id: String` - - `:standard` + The unique ID of the custom tool call output in the OpenAI platform. - - `:pro` + - `agent: Agent{ agent_name}` - - `summary: :auto | :concise | :detailed` + The agent that produced this item. - 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_name: String` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The canonical name of the agent that produced this item. - - `:auto` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:concise` + The execution context that produced this tool call. - - `:detailed` + - `class Direct` - - `safety_identifier: String` + - `type: :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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The caller type. Always `direct`. - - `service_tier: :auto | :default | :flex | 2 more` + - `:direct` - Specifies the processing type used for serving the request. + - `class 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](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'. + - `caller_id: 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 call ID of the program item that produced this tool call. - - `:auto` + - `type: :program` - - `:default` + The caller type. Always `program`. - - `:flex` + - `:program` - - `:scale` + - `class BetaResponseCustomToolCall` - - `:priority` + A call to a custom tool created by the model. - - `status: BetaResponseStatus` + - `call_id: String` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + An identifier used to map this custom tool call to a tool call output. - - `:completed` + - `input: String` - - `:failed` + The input for the custom tool call generated by the model. - - `:in_progress` + - `name: String` - - `:cancelled` + The name of the custom tool being called. - - `:queued` + - `type: :custom_tool_call` - - `:incomplete` + The type of the custom tool call. Always `custom_tool_call`. - - `text: BetaResponseTextConfig` + - `:custom_tool_call` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `id: String` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The unique ID of the custom tool call in the OpenAI platform. - - `format_: BetaResponseFormatTextConfig` + - `agent: Agent{ 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_: Direct{ type} | Program{ 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. - - `class Text` + - `class Direct` - Default response format. Used to generate text responses. + - `type: :direct` - - `type: :text` + - `:direct` - The type of response format being defined. Always `text`. + - `class Program` - - `:text` + - `caller_id: String` - - `class BetaResponseFormatTextJSONSchemaConfig` + 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. + - `namespace: String` - - `schema: Hash[Symbol, untyped]` + The namespace of the custom tool being called. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `class CompactionTrigger` - - `type: :json_schema` + Compacts the current context. Must be the final input item. - The type of response format being defined. Always `json_schema`. + - `type: :compaction_trigger` - - `:json_schema` + The type of the item. Always `compaction_trigger`. - - `description: 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: Agent{ agent_name}` - - `strict: bool` + 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). + - `agent_name: String` - - `class JSONObject` + The canonical name of 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. + - `class ItemReference` - - `type: :json_object` + An internal identifier for an item to reference. - The type of response format being defined. Always `json_object`. + - `id: String` - - `:json_object` + The ID of the item to reference. - - `verbosity: :low | :medium | :high` + - `agent: Agent{ agent_name}` - 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 agent that produced this item. - - `:low` + - `agent_name: String` - - `:medium` + The canonical name of the agent that produced this item. - - `:high` + - `type: :item_reference` - - `top_logprobs: Integer` + The type of item to reference. Always `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. + - `:item_reference` - - `truncation: :auto | :disabled` + - `class Program` - The truncation strategy to use for the model response. + - `id: 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 unique ID of this program item. - - `:auto` + - `call_id: String` - - `:disabled` + The stable call ID of the program item. - - `usage: BetaResponseUsage` + - `code: String` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The JavaScript source executed by programmatic tool calling. - - `input_tokens: Integer` + - `fingerprint: String` - The number of input tokens. + Opaque program replay fingerprint that must be round-tripped. - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `type: :program` - A detailed breakdown of the input tokens. + The item type. Always `program`. - - `cache_write_tokens: Integer` + - `:program` - The number of input tokens that were written to the cache. + - `agent: Agent{ agent_name}` - - `cached_tokens: Integer` + The agent that produced this item. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `agent_name: String` - - `output_tokens: Integer` + The canonical name of the agent that produced this item. - The number of output tokens. + - `class ProgramOutput` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `id: String` - A detailed breakdown of the output tokens. + The unique ID of this program output item. - - `reasoning_tokens: Integer` + - `call_id: String` - The number of reasoning tokens. + The call ID of the program item. - - `total_tokens: Integer` + - `result: String` - The total number of tokens used. + The result produced by the program item. - - `user: String` + - `status: :completed | :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). + The terminal status of the program output. -### Example + - `:completed` -```ruby -require "openai" + - `:incomplete` -openai = OpenAI::Client.new(api_key: "My API Key") + - `type: :program_output` -beta_response = openai.beta.responses.cancel("resp_677efb5139a88190b512bc3fef8e535d") + The item type. Always `program_output`. -puts(beta_response) -``` + - `:program_output` -#### Response + - `agent: Agent{ agent_name}` -```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" -} -``` + The agent that produced this item. -## Compact a response + - `agent_name: String` -`beta.responses.compact(**kwargs) -> BetaCompactedResponse` + The canonical name of the agent that produced this item. -**post** `/responses/compact?beta=true` + - `metadata: Hash[Symbol, String]` -Compact a response + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. -### Parameters + 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + 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. - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + 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"` @@ -38890,401 +48848,362 @@ Compact a response - `String = String` -- `input: String | Array[BetaResponseInputItem]` - - Text, image, or file inputs to the model, used to generate a response + - `object: :response` - - `String = String` + The object type of this resource - always set to `response`. - A text input to the model, equivalent to a text input with the `user` role. + - `:response` - - `UnionMember1 = Array[BetaResponseInputItem]` + - `output: Array[BetaResponseOutputItem]` - A list of one or many input items to the model, containing different content types. + An array of content items generated by the model. - - `class BetaEasyInputMessage` + - 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 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. + - `class BetaResponseOutputMessage` - - `content: String | BetaResponseInputMessageContentList` + An output message from the model. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `class BetaResponseFileSearchToolCall` - - `String = String` + 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 text input to the model. + - `class BetaResponseFunctionToolCall` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - A list of one or many input items to the model, containing different content - types. + - `class BetaResponseFunctionToolCallOutputItem` - - `class BetaResponseInputText` + - `id: String` - A text input to the model. + The unique ID of the function call tool output. - - `text: String` + - `call_id: String` - The text input to the model. + The unique ID of the function tool call generated by the model. - - `type: :input_text` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The type of the input item. Always `input_text`. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:input_text` + - `String = String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A string of the output of the function 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. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `mode: :explicit` + Text, image, or file output of the function call. - The breakpoint mode. Always `explicit`. + - `class BetaResponseInputText` - - `:explicit` + A text input to the model. - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: :low | :high | :auto | :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: String` - - The ID of the file to be sent to the model. - - - `image_url: 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: PromptCacheBreakpoint{ 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` - - `class BetaResponseInputFile` A file input to the model. - - `type: :input_file` + - `status: :in_progress | :completed | :incomplete` - The type of the input item. Always `input_file`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:input_file` + - `:in_progress` - - `detail: :auto | :low | :high` + - `:completed` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `:incomplete` - - `:auto` + - `type: :function_call_output` - - `:low` + The type of the function tool call output. Always `function_call_output`. - - `:high` + - `:function_call_output` - - `file_data: String` + - `agent: Agent{ agent_name}` - The content of the file to be sent to the model. + The agent that produced this item. - - `file_id: String` + - `agent_name: String` - The ID of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_url: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The URL of the file to be sent to the model. + The execution context that produced this tool call. - - `filename: String` + - `class Direct` - The name of the file to be sent to the model. + - `type: :direct` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The caller type. Always `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` + - `class Program` - The breakpoint mode. Always `explicit`. + - `caller_id: String` - - `:explicit` + The call ID of the program item that produced this tool call. - - `role: :user | :assistant | :system | :developer` + - `type: :program` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The caller type. Always `program`. - - `:user` + - `:program` - - `:assistant` + - `created_by: String` - - `:system` + The identifier of the actor that created the item. - - `:developer` + - `class AgentMessage` - - `phase: :commentary` + - `id: String` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The unique ID of the agent message. - - `:commentary` + - `author: String` - - `type: :message` + The sending agent identity. - The type of the message input. Always `message`. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `:message` + Encrypted content sent between agents. - - `class Message` + - `class BetaResponseInputText` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + A text input to the model. - - `content: BetaResponseInputMessageContentList` + - `class BetaResponseOutputText` - A list of one or many input items to the model, containing different content - types. + A text output from the model. - - `role: :user | :system | :developer` + - `class Text` - The role of the message input. One of `user`, `system`, or `developer`. + A text content. - - `:user` + - `text: String` - - `:system` + - `type: :text` - - `:developer` + - `:text` - - `agent: Agent{ agent_name}` + - `class SummaryText` - The agent that produced this item. + A summary text from the model. - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. - - `status: :in_progress | :completed | :incomplete` + - `type: :summary_text` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the object. Always `summary_text`. - - `:in_progress` + - `:summary_text` - - `:completed` + - `class ReasoningText` - - `:incomplete` + Reasoning text from the model. - - `type: :message` + - `text: String` - The type of the message input. Always set to `message`. + The reasoning text from the model. - - `:message` + - `type: :reasoning_text` - - `class BetaResponseOutputMessage` + The type of the reasoning text. Always `reasoning_text`. - An output message from the model. + - `:reasoning_text` - - `id: String` + - `class BetaResponseOutputRefusal` - The unique ID of the output message. + A refusal from the model. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `class BetaResponseInputImage` - The content of the output message. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaResponseOutputText` + - `class ComputerScreenshot` - A text output from the model. + A screenshot of a computer. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `detail: :low | :high | :auto | :original` - The annotations of the text output. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class FileCitation` + - `:low` - A citation to a file. + - `:high` + + - `:auto` + + - `:original` - `file_id: String` - The ID of the file. + The identifier of an uploaded file that contains the screenshot. - - `filename: String` + - `image_url: String` - The filename of the file cited. + The URL of the screenshot image. - - `index: Integer` + - `type: :computer_screenshot` - The index of the file in the list of files. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `type: :file_citation` + - `:computer_screenshot` - The type of the file citation. Always `file_citation`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:file_citation` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class URLCitation` + - `mode: :explicit` - A citation for a web resource used to generate a model response. + The breakpoint mode. Always `explicit`. - - `end_index: Integer` + - `:explicit` - The index of the last character of the URL citation in the message. + - `class BetaResponseInputFile` - - `start_index: Integer` + A file input to the model. - The index of the first character of the URL citation in the message. + - `class EncryptedContent` - - `title: String` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The title of the web resource. + - `encrypted_content: String` - - `type: :url_citation` + Opaque encrypted content. - The type of the URL citation. Always `url_citation`. + - `type: :encrypted_content` - - `:url_citation` + The type of the input item. Always `encrypted_content`. - - `url: String` + - `:encrypted_content` - The URL of the web resource. + - `recipient: String` - - `class ContainerFileCitation` + The destination agent identity. - A citation for a container file used to generate a model response. + - `type: :agent_message` - - `container_id: String` + The type of the item. Always `agent_message`. - The ID of the container file. + - `:agent_message` - - `end_index: Integer` + - `agent: Agent{ 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` + - `class MultiAgentCall` - The filename of the container file cited. + - `id: String` - - `start_index: Integer` + The unique ID of the multi-agent call item. - The index of the first character of the container file citation in the message. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :container_file_citation` + The multi-agent action to execute. - The type of the container file citation. Always `container_file_citation`. + - `:spawn_agent` - - `:container_file_citation` + - `:interrupt_agent` - - `class FilePath` + - `:list_agents` - A path to a file. + - `:send_message` - - `file_id: String` + - `:followup_task` - The ID of the file. + - `:wait_agent` - - `index: Integer` + - `arguments: String` - The index of the file in the list of files. + The JSON string of arguments generated for the action. - - `type: :file_path` + - `call_id: String` - The type of the file path. Always `file_path`. + The unique ID linking this call to its output. - - `:file_path` + - `type: :multi_agent_call` - - `text: String` + The type of the multi-agent call. Always `multi_agent_call`. - The text output from the model. + - `:multi_agent_call` - - `type: :output_text` + - `agent: Agent{ agent_name}` - The type of the output text. Always `output_text`. + The agent that produced this item. - - `:output_text` + - `agent_name: String` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The canonical name of the agent that produced this item. - - `token: String` + - `class MultiAgentCallOutput` - - `bytes: Array[Integer]` + - `id: String` - - `logprob: Float` + The unique ID of the multi-agent call output item. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `token: String` + The multi-agent action that produced this result. - - `bytes: Array[Integer]` + - `:spawn_agent` - - `logprob: Float` + - `:interrupt_agent` - - `class BetaResponseOutputRefusal` + - `:list_agents` - A refusal from the model. + - `:send_message` - - `refusal: String` + - `:followup_task` - The refusal explanation from the model. + - `:wait_agent` - - `type: :refusal` + - `call_id: String` - The type of the refusal. Always `refusal`. + The unique ID of the multi-agent call. - - `:refusal` + - `output: Array[BetaResponseOutputText]` - - `role: :assistant` + Text output returned by the multi-agent action. - The role of the output message. Always `assistant`. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:assistant` + The annotations of the text output. - - `status: :in_progress | :completed | :incomplete` + - `text: String` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The text output from the model. - - `:in_progress` + - `type: :output_text` - - `:completed` + The type of the output text. Always `output_text`. - - `:incomplete` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `type: :message` + - `type: :multi_agent_call_output` - The type of the output message. Always `message`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `:message` + - `:multi_agent_call_output` - `agent: Agent{ agent_name}` @@ -39294,35 +49213,34 @@ Compact a response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `class BetaResponseFunctionWebSearch` - 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 results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `:commentary` + - `class BetaResponseComputerToolCall` - - `class BetaResponseFileSearchToolCall` + 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 results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class BetaResponseComputerToolCallOutputItem` - `id: String` - The unique ID of the file search tool call. + The unique ID of the computer call tool output. - - `queries: Array[String]` + - `call_id: String` - The queries used to search for files. + The ID of the computer tool call that produced the output. - - `status: :in_progress | :searching | :completed | 2 more` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + A computer screenshot image used with the computer use tool. - - `:in_progress` + - `status: :completed | :incomplete | :failed | :in_progress` - - `:searching` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `:completed` @@ -39330,70 +49248,18 @@ Compact a response - `:failed` - - `type: :file_search_call` - - The type of the file search tool call. Always `file_search_call`. - - - `:file_search_call` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - The results of the file search tool call. - - - `attributes: Hash[Symbol, String | Float | bool]` - - Set of 16 key-value pairs that can be attached to an object. 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 = String` - - - `Float = Float` - - - `UnionMember2 = bool` - - - `file_id: String` - - The unique ID of the file. - - - `filename: String` - - The name of the file. - - - `score: Float` - - The relevance score of the file - a value between 0 and 1. - - - `text: String` - - The text that was retrieved from the file. - - - `class BetaResponseComputerToolCall` - - 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` + - `:in_progress` - The unique ID of the computer call. + - `type: :computer_call_output` - - `call_id: String` + The type of the computer tool call output. Always `computer_call_output`. - An identifier used when responding to the tool call with output. + - `:computer_call_output` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The pending safety checks for the computer call. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: String` @@ -39407,258 +49273,244 @@ Compact a response Details about the pending safety check. - - `status: :in_progress | :completed | :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`. + - `agent: Agent{ agent_name}` - - `:computer_call` + The agent that produced this item. - - `action: BetaComputerAction` + - `agent_name: String` - A click action. + The canonical name of the agent that produced this item. - - `class Click` + - `created_by: String` - A click action. + The identifier of the actor that created the item. - - `button: :left | :right | :wheel | 2 more` + - `class BetaResponseReasoningItem` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + 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). - - `:left` + - `class Program` - - `:right` + - `id: String` - - `:wheel` + The unique ID of the program item. - - `:back` + - `call_id: String` - - `:forward` + The stable call ID of the program item. - - `type: :click` + - `code: String` - Specifies the event type. For a click action, this property is always `click`. + The JavaScript source executed by programmatic tool calling. - - `:click` + - `fingerprint: String` - - `x: Integer` + Opaque program replay fingerprint that must be round-tripped. - The x-coordinate where the click occurred. + - `type: :program` - - `y_: Integer` + The type of the item. Always `program`. - The y-coordinate where the click occurred. + - `:program` - - `keys: Array[String]` + - `agent: Agent{ agent_name}` - The keys being held while clicking. + The agent that produced this item. - - `class DoubleClick` + - `agent_name: String` - A double click action. + The canonical name of the agent that produced this item. - - `keys: Array[String]` + - `class ProgramOutput` - The keys being held while double-clicking. + - `id: String` - - `type: :double_click` + The unique ID of the program output item. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `call_id: String` - - `:double_click` + The call ID of the program item. - - `x: Integer` + - `result: String` - The x-coordinate where the double click occurred. + The result produced by the program item. - - `y_: Integer` + - `status: :completed | :incomplete` - The y-coordinate where the double click occurred. + The terminal status of the program output item. - - `class Drag` + - `:completed` - A drag action. + - `:incomplete` - - `path: Array[Path{ x, y_}]` + - `type: :program_output` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The type of the item. Always `program_output`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `:program_output` - - `x: Integer` + - `agent: Agent{ agent_name}` - The x-coordinate. + The agent that produced this item. - - `y_: Integer` + - `agent_name: String` - The y-coordinate. + The canonical name of the agent that produced this item. - - `type: :drag` + - `class BetaResponseToolSearchCall` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: String` - - `:drag` + The unique ID of the tool search call item. - - `keys: Array[String]` + - `arguments: untyped` - The keys being held while dragging the mouse. + Arguments used for the tool search call. - - `class Keypress` + - `call_id: String` - A collection of keypresses the model would like to perform. + The unique ID of the tool search call generated by the model. - - `keys: Array[String]` + - `execution: :server | :client` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Whether tool search was executed by the server or by the client. - - `type: :keypress` + - `:server` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `:client` - - `:keypress` + - `status: :in_progress | :completed | :incomplete` - - `class Move` + The status of the tool search call item that was recorded. - 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` + - `type: :tool_search_call` - - `x: Integer` + The type of the item. Always `tool_search_call`. - The x-coordinate to move to. + - `:tool_search_call` - - `y_: Integer` + - `agent: Agent{ agent_name}` - The y-coordinate to move to. + The agent that produced this item. - - `keys: Array[String]` + - `agent_name: String` - The keys being held while moving the mouse. + The canonical name of the agent that produced this item. - - `class Screenshot` + - `created_by: String` - A screenshot action. + The identifier of the actor that created the item. - - `type: :screenshot` + - `class BetaResponseToolSearchOutputItem` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `id: String` - - `:screenshot` + The unique ID of the tool search output item. - - `class Scroll` + - `call_id: String` - A scroll action. + The unique ID of the tool search call generated by the model. - - `scroll_x: Integer` + - `execution: :server | :client` - The horizontal scroll distance. + Whether tool search was executed by the server or by the client. - - `scroll_y: Integer` + - `:server` - The vertical scroll distance. + - `:client` - - `type: :scroll` + - `status: :in_progress | :completed | :incomplete` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The status of the tool search output item that was recorded. - - `:scroll` + - `:in_progress` - - `x: Integer` + - `:completed` - The x-coordinate where the scroll occurred. + - `:incomplete` - - `y_: Integer` + - `tools: Array[BetaTool]` - The y-coordinate where the scroll occurred. + The loaded tool definitions returned by tool search. - - `keys: Array[String]` + - `class BetaFunctionTool` - The keys being held while scrolling. + 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). - - `class Type` + - `class BetaFileSearchTool` - An action to type in 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). - - `text: String` + - `class BetaComputerTool` - The text to type. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :type` + - `class BetaComputerUsePreviewTool` - Specifies the event type. For a type action, this property is always set to `type`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:type` + - `class BetaWebSearchTool` - - `class Wait` + 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 wait action. + - `class Mcp` - - `type: :wait` + 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). - Specifies the event type. For a wait action, this property is always set to `wait`. + - `class CodeInterpreter` - - `:wait` + A tool that runs Python code to help generate a response to a prompt. - - `actions: BetaComputerActionList` + - `class ProgrammaticToolCalling` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `class ImageGeneration` - - `class Click` + A tool that generates images using the GPT image models. - A click action. + - `class LocalShell` - - `class DoubleClick` + A tool that allows the model to execute shell commands in a local environment. - A double click action. + - `class BetaFunctionShellTool` - - `class Drag` + A tool that allows the model to execute shell commands. - A drag action. + - `class BetaCustomTool` - - `class Keypress` + 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 collection of keypresses the model would like to perform. + - `class BetaNamespaceTool` - - `class Move` + Groups function/custom tools under a shared namespace. - A mouse move action. + - `class BetaToolSearchTool` - - `class Screenshot` + Hosted or BYOT tool search configuration for deferred tools. - A screenshot action. + - `class BetaWebSearchPreviewTool` - - `class Scroll` + 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 scroll action. + - `class BetaApplyPatchTool` - - `class Type` + Allows the assistant to create, delete, or update files using unified diffs. - An action to type in text. + - `type: :tool_search_output` - - `class Wait` + The type of the item. Always `tool_search_output`. - A wait action. + - `:tool_search_output` - `agent: Agent{ agent_name}` @@ -39668,172 +49520,135 @@ Compact a response The canonical name of the agent that produced this item. - - `class ComputerCallOutput` - - 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: String` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: 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: String` - - The ID of the computer tool call output. + - `created_by: String` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + The identifier of the actor that created the item. - The safety checks reported by the API that have been acknowledged by the developer. + - `class AdditionalTools` - `id: String` - The ID of the pending safety check. - - - `code: String` + The unique ID of the additional tools item. - The type of the pending safety check. + - `role: :unknown | :user | :assistant | 5 more` - - `message: String` + The role that provided the additional tools. - Details about the pending safety check. + - `:unknown` - - `agent: Agent{ agent_name}` + - `:user` - The agent that produced this item. + - `:assistant` - - `agent_name: String` + - `:system` - The canonical name of the agent that produced this item. + - `:critic` - - `status: :in_progress | :completed | :incomplete` + - `:discriminator` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `:developer` - - `:in_progress` + - `:tool` - - `:completed` + - `tools: Array[BetaTool]` - - `:incomplete` + The additional tool definitions made available at this item. - - `class BetaResponseFunctionWebSearch` + - `class BetaFunctionTool` - 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. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `id: String` + - `class BetaFileSearchTool` - The unique ID of the web search 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). - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `class BetaComputerTool` - 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 controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class Search` + - `class BetaComputerUsePreviewTool` - Action type "search" - Performs a web search query. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :search` + - `class BetaWebSearchTool` - The action 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). - - `:search` + - `class Mcp` - - `queries: Array[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 search queries. + - `class CodeInterpreter` - - `query: String` + A tool that runs Python code to help generate a response to a prompt. - The search query. + - `class ProgrammaticToolCalling` - - `sources: Array[Source{ type, url}]` + - `class ImageGeneration` - The sources used in the search. + A tool that generates images using the GPT image models. - - `type: :url` + - `class LocalShell` - The type of source. Always `url`. + A tool that allows the model to execute shell commands in a local environment. - - `:url` + - `class BetaFunctionShellTool` - - `url: String` + A tool that allows the model to execute shell commands. - The URL of the source. + - `class BetaCustomTool` - - `class OpenPage` + 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) - Action type "open_page" - Opens a specific URL from search results. + - `class BetaNamespaceTool` - - `type: :open_page` + Groups function/custom tools under a shared namespace. - The action type. + - `class BetaToolSearchTool` - - `:open_page` + Hosted or BYOT tool search configuration for deferred tools. - - `url: String` + - `class BetaWebSearchPreviewTool` - The URL opened by the model. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class FindInPage` + - `class BetaApplyPatchTool` - Action type "find_in_page": Searches for a pattern within a loaded page. + Allows the assistant to create, delete, or update files using unified diffs. - - `pattern: String` + - `type: :additional_tools` - The pattern or text to search for within the page. + The type of the item. Always `additional_tools`. - - `type: :find_in_page` + - `:additional_tools` - The action type. + - `agent: Agent{ agent_name}` - - `:find_in_page` + The agent that produced this item. - - `url: String` + - `agent_name: String` - The URL of the page searched for the pattern. + The canonical name of the agent that produced this item. - - `status: :in_progress | :searching | :completed | :failed` + - `class BetaResponseCompactionItem` - The status of the web search tool call. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:in_progress` + - `id: String` - - `:searching` + The unique ID of the compaction item. - - `:completed` + - `encrypted_content: String` - - `:failed` + The encrypted content that was produced by compaction. - - `type: :web_search_call` + - `type: :compaction` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `compaction`. - - `:web_search_call` + - `:compaction` - `agent: Agent{ agent_name}` @@ -39843,32 +49658,39 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall` + - `created_by: String` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The identifier of the actor that created the item. - - `arguments: String` + - `class ImageGenerationCall` - A JSON string of the arguments to pass to the function. + An image generation request made by the model. - - `call_id: String` + - `id: String` - The unique ID of the function tool call generated by the model. + The unique ID of the image generation call. - - `name: String` + - `result: String` - The name of the function to run. + The generated image encoded in base64. - - `type: :function_call` + - `status: :in_progress | :completed | :generating | :failed` - The type of the function tool call. Always `function_call`. + The status of the image generation call. - - `:function_call` + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of the function tool call. + - `:generating` + + - `:failed` + + - `type: :image_generation_call` + + The type of the image generation call. Always `image_generation_call`. + + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -39878,180 +49700,179 @@ Compact a response The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseCodeInterpreterToolCall` - The execution context that produced this tool call. + A tool call to run code. - - `class Direct` + - `class LocalShellCall` - - `type: :direct` + A tool call to run a command on the local shell. - - `:direct` + - `id: String` - - `class Program` + The unique ID of the local shell call. - - `caller_id: String` + - `action: Action{ command, env, type, 3 more}` - The call ID of the program item that produced this tool call. + Execute a shell command on the server. - - `type: :program` + - `command: Array[String]` - - `:program` + The command to run. - - `namespace: String` + - `env: Hash[Symbol, String]` - The namespace of the function to run. + Environment variables to set for the command. - - `status: :in_progress | :completed | :incomplete` + - `type: :exec` - 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 action. Always `exec`. - - `:in_progress` + - `:exec` - - `:completed` + - `timeout_ms: Integer` - - `:incomplete` + Optional timeout in milliseconds for the command. - - `class FunctionCallOutput` + - `user: String` - The output of a function tool call. + Optional user to run the command as. - - `call_id: String` + - `working_directory: String` - The unique ID of the function tool call generated by the model. + Optional working directory to run the command in. - - `output: String | BetaResponseFunctionCallOutputItemList` + - `call_id: String` - Text, image, or file output of the function tool call. + The unique ID of the local shell tool call generated by the model. - - `String = String` + - `status: :in_progress | :completed | :incomplete` - A JSON string of the output of the function tool call. + The status of the local shell call. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `:in_progress` - An array of content outputs (text, image, file) for the function tool call. + - `:completed` - - `class BetaResponseInputTextContent` + - `:incomplete` - A text input to the model. + - `type: :local_shell_call` - - `text: String` + The type of the local shell call. Always `local_shell_call`. - The text input to the model. + - `:local_shell_call` - - `type: :input_text` + - `agent: Agent{ 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: PromptCacheBreakpoint{ 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. + - `class LocalShellCallOutput` - - `mode: :explicit` + The output of a local shell tool call. - The breakpoint mode. Always `explicit`. + - `id: String` - - `:explicit` + The unique ID of the local shell tool call generated by the model. - - `class BetaResponseInputImageContent` + - `output: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A JSON string of the output of the local shell tool call. - - `type: :input_image` + - `type: :local_shell_call_output` - The type of the input item. Always `input_image`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:input_image` + - `:local_shell_call_output` - - `detail: :low | :high | :auto | :original` + - `agent: Agent{ agent_name}` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `:low` + - `agent_name: String` - - `:high` + The canonical name of the agent that produced this item. - - `:auto` + - `status: :in_progress | :completed | :incomplete` - - `:original` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `file_id: String` + - `:in_progress` - The ID of the file to be sent to the model. + - `:completed` - - `image_url: String` + - `:incomplete` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class BetaResponseFunctionShellToolCall` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A tool call that executes one or more shell commands in a managed environment. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `id: String` - - `mode: :explicit` + The unique ID of the shell tool call. Populated when this item is returned via API. - The breakpoint mode. Always `explicit`. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:explicit` + The shell commands and limits that describe how to run the tool call. - - `class BetaResponseInputFileContent` + - `commands: Array[String]` - A file input to the model. + - `max_output_length: Integer` - - `type: :input_file` + Optional maximum number of characters to return from each command. - The type of the input item. Always `input_file`. + - `timeout_ms: Integer` - - `:input_file` + Optional timeout in milliseconds for the commands. - - `detail: :auto | :low | :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 shell tool call generated by the model. - - `:auto` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:low` + Represents the use of a local environment to perform shell actions. - - `:high` + - `class BetaResponseLocalEnvironment` - - `file_data: String` + Represents the use of a local environment to perform shell actions. - The base64-encoded data of the file to be sent to the model. + - `type: :local` - - `file_id: String` + The environment type. Always `local`. - The ID of the file to be sent to the model. + - `:local` - - `file_url: String` + - `class BetaResponseContainerReference` - The URL of the file to be sent to the model. + Represents a container created with /v1/containers. - - `filename: String` + - `container_id: String` - The name of the file to be sent to the model. + - `type: :container_reference` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The environment type. Always `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. + - `:container_reference` - - `mode: :explicit` + - `status: :in_progress | :completed | :incomplete` - The breakpoint mode. Always `explicit`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:explicit` + - `:in_progress` - - `type: :function_call_output` + - `:completed` - The type of the function tool call output. Always `function_call_output`. + - `:incomplete` - - `:function_call_output` + - `type: :shell_call` - - `id: String` + The type of the item. Always `shell_call`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `:shell_call` - `agent: Agent{ agent_name}` @@ -40069,8 +49890,6 @@ Compact a response - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -40081,111 +49900,87 @@ Compact a response - `type: :program` - The caller type. Always `program`. - - `:program` - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class AgentMessage` - - A message routed between agents. - - - `author: String` - - The sending agent identity. - - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - Plaintext, image, or encrypted content sent between agents. - - - `class BetaResponseInputTextContent` + - `created_by: String` - A text input to the model. + The ID of the entity that created this tool call. - - `class BetaResponseInputImageContent` + - `class BetaResponseFunctionShellToolCallOutput` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The output of a shell tool call that was emitted. - - `class EncryptedContent` + - `id: String` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The unique ID of the shell call output. Populated when this item is returned via API. - - `encrypted_content: String` + - `call_id: String` - Opaque encrypted content. + The unique ID of the shell tool call generated by the model. - - `type: :encrypted_content` + - `max_output_length: Integer` - The type of the input item. Always `encrypted_content`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `:encrypted_content` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `recipient: String` + An array of shell call output contents - The destination agent identity. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `type: :agent_message` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The item type. Always `agent_message`. + - `class Timeout` - - `:agent_message` + Indicates that the shell call exceeded its configured time limit. - - `id: String` + - `type: :timeout` - The unique ID of this agent message item. + The outcome type. Always `timeout`. - - `agent: Agent{ agent_name}` + - `:timeout` - The agent that produced this item. + - `class Exit` - - `agent_name: String` + Indicates that the shell commands finished and returned an exit code. - The canonical name of the agent that produced this item. + - `exit_code: Integer` - - `class MultiAgentCall` + Exit code from the shell process. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :exit` - The multi-agent action that was executed. + The outcome type. Always `exit`. - - `:spawn_agent` + - `:exit` - - `:interrupt_agent` + - `stderr: String` - - `:list_agents` + The standard error output that was captured. - - `:send_message` + - `stdout: String` - - `:followup_task` + The standard output that was captured. - - `:wait_agent` + - `created_by: String` - - `arguments: String` + The identifier of the actor that created the item. - The action arguments as a JSON string. + - `status: :in_progress | :completed | :incomplete` - - `call_id: String` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID linking this call to its output. + - `:in_progress` - - `type: :multi_agent_call` + - `:completed` - The item type. Always `multi_agent_call`. + - `:incomplete` - - `:multi_agent_call` + - `type: :shell_call_output` - - `id: String` + The type of the shell call output. Always `shell_call_output`. - The unique ID of this multi-agent call. + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -40195,127 +49990,109 @@ Compact a response The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput` - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The unique ID of the multi-agent call. + The execution context that produced this tool call. - - `output: Array[Output{ text, type, annotations}]` + - `class Direct` - Text output returned by the multi-agent action. + - `type: :direct` - - `text: String` + - `:direct` - The text content. + - `class Program` - - `type: :output_text` + - `caller_id: String` - The content type. Always `output_text`. + The call ID of the program item that produced this tool call. - - `:output_text` + - `type: :program` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `:program` - Citations associated with the text content. + - `created_by: String` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + The identifier of the actor that created the item. - - `file_id: String` + - `class BetaResponseApplyPatchToolCall` - The ID of the file. + A tool call that applies file diffs by creating, deleting, or updating files. - - `filename: String` + - `id: String` - The filename of the file cited. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `index: Integer` + - `call_id: String` - The index of the file in the list of files. + The unique ID of the apply patch tool call generated by the model. - - `type: :file_citation` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The citation type. Always `file_citation`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `:file_citation` + - `class CreateFile` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + Instruction describing how to create a file via the apply_patch tool. - - `end_index: Integer` + - `diff: String` - The index of the last character of the citation in the message. + Diff to apply. - - `start_index: Integer` + - `path: String` - The index of the first character of the citation in the message. + Path of the file to create. - - `title: String` + - `type: :create_file` - The title of the cited resource. + Create a new file with the provided diff. - - `type: :url_citation` + - `:create_file` - The citation type. Always `url_citation`. + - `class DeleteFile` - - `:url_citation` + Instruction describing how to delete a file via the apply_patch tool. - - `url: String` + - `path: String` - The URL of the cited resource. + Path of the file to delete. - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `type: :delete_file` - - `container_id: String` + Delete the specified file. - The ID of the container. + - `:delete_file` - - `end_index: Integer` + - `class UpdateFile` - The index of the last character of the citation in the message. + Instruction describing how to update a file via the apply_patch tool. - - `file_id: String` + - `diff: String` - The ID of the container file. + Diff to apply. - - `filename: String` + - `path: String` - The filename of the container file cited. + Path of the file to update. - - `start_index: Integer` + - `type: :update_file` - The index of the first character of the citation in the message. + Update an existing file with the provided diff. - - `type: :container_file_citation` + - `:update_file` - The citation type. Always `container_file_citation`. + - `status: :in_progress | :completed` - - `:container_file_citation` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `type: :multi_agent_call_output` + - `:in_progress` - The item type. Always `multi_agent_call_output`. + - `:completed` - - `:multi_agent_call_output` + - `type: :apply_patch_call` - - `id: String` + The type of the item. Always `apply_patch_call`. - The unique ID of this multi-agent call output. + - `:apply_patch_call` - `agent: Agent{ agent_name}` @@ -40325,1364 +50102,1383 @@ Compact a response The canonical name of the agent that produced this item. - - `class ToolSearchCall` - - - `arguments: untyped` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The arguments supplied to the tool search call. + The execution context that produced this tool call. - - `type: :tool_search_call` + - `class Direct` - The item type. Always `tool_search_call`. + - `type: :direct` - - `:tool_search_call` + - `:direct` - - `id: String` + - `class Program` - The unique ID of this tool search call. + - `caller_id: String` - - `agent: Agent{ 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: String` - - `call_id: String` + The ID of the entity that created this tool call. - The unique ID of the tool search call generated by the model. + - `class BetaResponseApplyPatchToolCallOutput` - - `execution: :server | :client` + The output emitted by an apply patch tool call. - Whether tool search was executed by the server or by the client. + - `id: String` - - `:server` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `:client` + - `call_id: String` - - `status: :in_progress | :completed | :incomplete` + The unique ID of the apply patch tool call generated by the model. - The status of the tool search call. + - `status: :completed | :failed` - - `:in_progress` + The status of the apply patch tool call output. One of `completed` or `failed`. - `:completed` - - `:incomplete` - - - `class BetaResponseToolSearchOutputItemParam` - - - `tools: Array[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool` - - 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: :apply_patch_call_output` - The name of the function to call. + The type of the item. Always `apply_patch_call_output`. - - `parameters: Hash[Symbol, untyped]` + - `:apply_patch_call_output` - A JSON schema object describing the parameters of the function. + - `agent: Agent{ agent_name}` - - `strict: bool` + 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_: Direct{ type} | Program{ caller_id, type}` - - `:function` + The execution context that produced this tool call. - - `allowed_callers: Array[:direct | :programmatic]` + - `class Direct` - The tool invocation context(s). + - `type: :direct` - `:direct` - - `:programmatic` - - - `defer_loading: bool` - - Whether this function is deferred and loaded via tool search. - - - `description: String` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: Hash[Symbol, untyped]` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - - - `class BetaFileSearchTool` - - 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). + - `class Program` - - `type: :file_search` + - `caller_id: String` - The type of the file search tool. Always `file_search`. + The call ID of the program item that produced this tool call. - - `:file_search` + - `type: :program` - - `vector_store_ids: Array[String]` + - `:program` - The IDs of the vector stores to search. + - `created_by: String` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + The ID of the entity that created this tool call output. - A filter to apply. + - `output: String` - - `class ComparisonFilter` + Optional textual output returned by the apply patch tool. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class McpCall` - - `key: String` + An invocation of a tool on an MCP server. - The key to compare against the value. + - `id: String` - - `type: :eq | :ne | :gt | 5 more` + The unique ID of the tool call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `arguments: 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 JSON string of the arguments passed to the tool. - - `:eq` + - `name: String` - - `:ne` + The name of the tool that was run. - - `:gt` + - `server_label: String` - - `:gte` + The label of the MCP server running the tool. - - `:lt` + - `type: :mcp_call` - - `:lte` + The type of the item. Always `mcp_call`. - - `:in` + - `:mcp_call` - - `:nin` + - `agent: Agent{ agent_name}` - - `value: String | Float | bool | Array[untyped]` + The agent that produced this item. - The value to compare against the attribute key; supports string, number, or boolean types. + - `agent_name: String` - - `String = String` + The canonical name of the agent that produced this item. - - `Float = Float` + - `approval_request_id: String` - - `UnionMember2 = bool` + 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. - - `UnionMember3 = Array[untyped]` + - `error: String` - - `class CompoundFilter` + The error from the tool call, if any. - Combine multiple filters using `and` or `or`. + - `output: String` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The output from the tool call. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `class ComparisonFilter` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - 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. + - `:incomplete` - - `type: :eq | :ne | :gt | 5 more` + - `:calling` - 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 + - `class McpListTools` - - `:eq` + A list of tools available on an MCP server. - - `:ne` + - `id: String` - - `:gt` + The unique ID of the list. - - `:gte` + - `server_label: String` - - `:lt` + The label of the MCP server. - - `:lte` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `:in` + The tools available on the server. - - `:nin` + - `input_schema: untyped` - - `value: String | Float | bool | Array[untyped]` + The JSON schema describing the tool's input. - The value to compare against the attribute key; supports string, number, or boolean types. + - `name: String` - - `String = String` + The name of the tool. - - `Float = Float` + - `annotations: untyped` - - `UnionMember2 = bool` + Additional annotations about the tool. - - `UnionMember3 = Array[untyped]` + - `description: String` - - `UnionMember1 = untyped` + The description of the tool. - - `type: :and | :or` + - `type: :mcp_list_tools` - Type of operation: `and` or `or`. + The type of the item. Always `mcp_list_tools`. - - `:and` + - `:mcp_list_tools` - - `:or` + - `agent: Agent{ agent_name}` - - `max_num_results: Integer` + 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: RankingOptions{ hybrid_search, ranker, score_threshold}` + The canonical name of the agent that produced this item. - Ranking options for search. + - `error: String` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + Error message if the server could not list tools. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `class McpApprovalRequest` - - `embedding_weight: Float` + A request for human approval of a tool invocation. - The weight of the embedding in the reciprocal ranking fusion. + - `id: String` - - `text_weight: Float` + The unique ID of the approval request. - The weight of the text in the reciprocal ranking fusion. + - `arguments: String` - - `ranker: :auto | :"default-2024-11-15"` + A JSON string of arguments for the tool. - The ranker to use for the file search. + - `name: String` - - `:auto` + The name of the tool to run. - - `:"default-2024-11-15"` + - `server_label: String` - - `score_threshold: Float` + The label of the MCP server making the request. - 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_approval_request` - - `class BetaComputerTool` + The type of the item. Always `mcp_approval_request`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:mcp_approval_request` - - `type: :computer` + - `agent: Agent{ agent_name}` - The type of the computer tool. Always `computer`. + The agent that produced this item. - - `:computer` + - `agent_name: String` - - `class BetaComputerUsePreviewTool` + 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). + - `class McpApprovalResponse` - - `display_height: Integer` + A response to an MCP approval request. - The height of the computer display. + - `id: String` - - `display_width: Integer` + The unique ID of the approval response - The width of the computer display. + - `approval_request_id: String` - - `environment: :windows | :mac | :linux | 2 more` + The ID of the approval request being answered. - The type of computer environment to control. + - `approve: bool` - - `:windows` + Whether the request was approved. - - `:mac` + - `type: :mcp_approval_response` - - `:linux` + The type of the item. Always `mcp_approval_response`. - - `:ubuntu` + - `:mcp_approval_response` - - `:browser` + - `agent: Agent{ 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. - - `class BetaWebSearchTool` + - `reason: 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). + Optional reason for the decision. - - `type: :web_search | :web_search_2025_08_26` + - `class BetaResponseCustomToolCall` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A call to a custom tool created by the model. - - `:web_search` + - `class BetaResponseCustomToolCallOutputItem` - - `:web_search_2025_08_26` + The output of a custom tool call from your code, being sent back to the model. - - `filters: Filters{ allowed_domains}` + - `id: String` - Filters for the search. + The unique ID of the custom tool call output item. - - `allowed_domains: Array[String]` + - `status: :in_progress | :completed | :incomplete` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `:in_progress` - - `search_context_size: :low | :medium | :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` + - `created_by: String` - - `:medium` + The identifier of the actor that created the item. - - `:high` + - `parallel_tool_calls: bool` - - `user_location: UserLocation{ city, country, region, 2 more}` + Whether to allow the model to run tool calls in parallel. - The approximate location of the user. + - `temperature: Float` - - `city: 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. - Free text input for the city of the user, e.g. `San Francisco`. + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `country: 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 two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `BetaToolChoiceOptions = :none | :auto | :required` - - `region: String` + Controls which (if any) tool is called by the model. - Free text input for the region of the user, e.g. `California`. + `none` means the model will not call any tool and instead generates a message. - - `timezone: String` + `auto` means the model can pick between generating a message or calling one or + more tools. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + `required` means the model must call one or more tools. - - `type: :approximate` + - `:none` - The type of location approximation. Always `approximate`. + - `:auto` - - `:approximate` + - `:required` - - `class Mcp` + - `class BetaToolChoiceAllowed` - 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). + Constrains the tools available to the model to a pre-defined set. - - `server_label: String` + - `mode: :auto | :required` - A label for this MCP server, used to identify it in tool calls. + Constrains the tools available to the model to a pre-defined set. - - `type: :mcp` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The type of the MCP tool. Always `mcp`. + `required` requires the model to call one or more of the allowed tools. - - `:mcp` + - `:auto` - - `allowed_callers: Array[:direct | :programmatic]` + - `:required` - The tool invocation context(s). + - `tools: Array[Hash[Symbol, untyped]]` - - `:direct` + A list of tool definitions that the model should be allowed to call. - - `:programmatic` + For the Responses API, the list of tool definitions might look like: - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - List of allowed tool names or a filter object. + - `type: :allowed_tools` - - `McpAllowedTools = Array[String]` + Allowed tool configuration type. Always `allowed_tools`. - A string array of allowed tool names + - `:allowed_tools` - - `class McpToolFilter` + - `class BetaToolChoiceTypes` - A filter object to specify which tools are allowed. + 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). - - `read_only: bool` + - `type: :file_search | :web_search_preview | :computer | 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 type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `tool_names: Array[String]` + Allowed values are: - List of allowed tool names. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `authorization: String` + - `: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. + - `:web_search_preview` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:computer` - 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). + - `:computer_use_preview` - Currently supported `connector_id` values are: + - `:computer_use` - - 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` + - `:web_search_preview_2025_03_11` - - `:connector_dropbox` + - `:image_generation` - - `:connector_gmail` + - `:code_interpreter` - - `:connector_googlecalendar` + - `class BetaToolChoiceFunction` - - `:connector_googledrive` + Use this option to force the model to call a specific function. - - `:connector_microsoftteams` + - `name: String` - - `:connector_outlookcalendar` + The name of the function to call. - - `:connector_outlookemail` + - `type: :function` - - `:connector_sharepoint` + For function calling, the type is always `function`. - - `defer_loading: bool` + - `:function` - Whether this MCP tool is deferred and discovered via tool search. + - `class BetaToolChoiceMcp` - - `headers: Hash[Symbol, String]` + Use this option to force the model to call a specific tool on a remote MCP server. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `server_label: String` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + The label of the MCP server to use. - Specify which of the MCP server's tools require approval. + - `type: :mcp` - - `class McpToolApprovalFilter` + For MCP tools, the type is always `mcp`. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `:mcp` - - `always: Always{ read_only, tool_names}` + - `name: String` - A filter object to specify which tools are allowed. + The name of the tool to call on the server. - - `read_only: bool` + - `class BetaToolChoiceCustom` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Use this option to force the model to call a specific custom tool. - - `tool_names: Array[String]` + - `name: String` - List of allowed tool names. + The name of the custom tool to call. - - `never: Never{ read_only, tool_names}` + - `type: :custom` - A filter object to specify which tools are allowed. + For custom tool calling, the type is always `custom`. - - `read_only: bool` + - `:custom` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class BetaSpecificProgrammaticToolCallingParam` - - `tool_names: Array[String]` + - `type: :programmatic_tool_calling` - List of allowed tool names. + The tool to call. Always `programmatic_tool_calling`. - - `McpToolApprovalSetting = :always | :never` + - `:programmatic_tool_calling` - 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. + - `class BetaToolChoiceApplyPatch` - - `:always` + Forces the model to call the apply_patch tool when executing a tool call. - - `:never` + - `type: :apply_patch` - - `server_description: String` + The tool to call. Always `apply_patch`. - Optional description of the MCP server, used to provide more context. + - `:apply_patch` - - `server_url: String` + - `class BetaToolChoiceShell` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Forces the model to call the shell tool when a tool call is required. - - `tunnel_id: String` + - `type: :shell` - 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 tool to call. Always `shell`. - - `class CodeInterpreter` + - `:shell` - A tool that runs Python code to help generate a response to a prompt. + - `tools: Array[BetaTool]` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - The 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. + We support the following categories of tools: - - `String = 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 container ID. + - `class BetaFunctionTool` - - `class CodeInterpreterToolAuto` + 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). - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `class BetaFileSearchTool` - - `type: :auto` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Always `auto`. + - `class BetaComputerTool` - - `:auto` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `file_ids: Array[String]` + - `class BetaComputerUsePreviewTool` - An optional list of uploaded files to make available to your code. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class BetaWebSearchTool` - The memory limit for the code interpreter container. + 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). - - `:"1g"` + - `class Mcp` - - `:"4g"` + 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). - - `:"16g"` + - `class CodeInterpreter` - - `:"64g"` + A tool that runs Python code to help generate a response to a prompt. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `class ProgrammaticToolCalling` - Network access policy for the container. + - `class ImageGeneration` - - `class BetaContainerNetworkPolicyDisabled` + A tool that generates images using the GPT image models. - - `type: :disabled` + - `class LocalShell` - Disable outbound network access. Always `disabled`. + A tool that allows the model to execute shell commands in a local environment. - - `:disabled` + - `class BetaFunctionShellTool` - - `class BetaContainerNetworkPolicyAllowlist` + A tool that allows the model to execute shell commands. - - `allowed_domains: Array[String]` + - `class BetaCustomTool` - A list of allowed domains when type is `allowlist`. + 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: :allowlist` + - `class BetaNamespaceTool` - Allow outbound network access only to specified domains. Always `allowlist`. + Groups function/custom tools under a shared namespace. - - `:allowlist` + - `class BetaToolSearchTool` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + Hosted or BYOT tool search configuration for deferred tools. - Optional domain-scoped secrets for allowlisted domains. + - `class BetaWebSearchPreviewTool` - - `domain: 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 domain associated with the secret. + - `class BetaApplyPatchTool` - - `name: String` + Allows the assistant to create, delete, or update files using unified diffs. - The name of the secret to inject for the domain. + - `top_p: Float` - - `value: 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 secret value to inject for the domain. + We generally recommend altering this or `temperature` but not both. - - `type: :code_interpreter` + - `background: bool` - The type of the code interpreter tool. Always `code_interpreter`. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `:code_interpreter` + - `completed_at: Float` - - `allowed_callers: Array[:direct | :programmatic]` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The tool invocation context(s). + - `conversation: Conversation{ id}` - - `:direct` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `:programmatic` + - `id: String` - - `class ProgrammaticToolCalling` + The unique ID of the conversation that this response was associated with. - - `type: :programmatic_tool_calling` + - `max_output_tokens: Integer` - The type of the tool. Always `programmatic_tool_calling`. + 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). - - `:programmatic_tool_calling` + - `max_tool_calls: Integer` - - `class ImageGeneration` + 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 tool that generates images using the GPT image models. + - `moderation: Moderation{ input, output}` - - `type: :image_generation` + Moderation results for the response input and output, if moderated completions were requested. - The type of the image generation tool. Always `image_generation`. + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `:image_generation` + Moderation for the response input. - - `action: :generate | :edit | :auto` + - `class ModerationResult` - Whether to generate a new image or edit an existing image. Default: `auto`. + A moderation result produced for the response input or output. - - `:generate` + - `categories: Hash[Symbol, bool]` - - `:edit` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:auto` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `background: :transparent | :opaque | :auto` + Which modalities of input are reflected by the score for each category. - 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. + - `:text` - `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. + - `:image` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `category_scores: Hash[Symbol, Float]` - - `:transparent` + A dictionary of moderation categories to scores. - - `:opaque` + - `flagged: bool` - - `:auto` + A boolean indicating whether the content was flagged by any category. - - `input_fidelity: :high | :low` + - `model: 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 moderation model that produced this result. - - `:high` + - `type: :moderation_result` - - `:low` + The object type, which was always `moderation_result` for successful moderation results. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `:moderation_result` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `class Error` - - `file_id: String` + An error produced while attempting moderation for the response input or output. - File ID for the mask image. + - `code: String` - - `image_url: String` + The error code. - Base64-encoded mask image. + - `message: String` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The error message. - The image generation model to use. Default: `gpt-image-1`. + - `type: :error` - - `String = String` + The object type, which was always `error` for moderation failures. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `:error` - The image generation model to use. Default: `gpt-image-1`. + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `:"gpt-image-1"` + Moderation for the response output. - - `:"gpt-image-1-mini"` + - `class ModerationResult` - - `:"gpt-image-2"` + A moderation result produced for the response input or output. - - `:"gpt-image-2-2026-04-21"` + - `categories: Hash[Symbol, bool]` - - `:"gpt-image-1.5"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:"chatgpt-image-latest"` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `moderation: :auto | :low` + Which modalities of input are reflected by the score for each category. - Moderation level for the generated image. Default: `auto`. + - `:text` - - `:auto` + - `:image` - - `:low` + - `category_scores: Hash[Symbol, Float]` - - `output_compression: Integer` + A dictionary of moderation categories to scores. - Compression level for the output image. Default: 100. + - `flagged: bool` - - `output_format: :png | :webp | :jpeg` + A boolean indicating whether the content was flagged by any category. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `model: String` - - `:png` + The moderation model that produced this result. - - `:webp` + - `type: :moderation_result` - - `:jpeg` + The object type, which was always `moderation_result` for successful moderation results. - - `partial_images: Integer` + - `:moderation_result` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `class Error` - - `quality: :low | :medium | :high | :auto` + An error produced while attempting moderation for the response input or output. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `code: String` - - `:low` + The error code. - - `:medium` + - `message: String` - - `:high` + The error message. - - `:auto` + - `type: :error` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + The object type, which was always `error` for moderation failures. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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` - - `String = String` + - `previous_response_id: String` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + 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 size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `prompt: BetaResponsePrompt` - - `:"1024x1024"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `:"1024x1536"` + - `id: String` - - `:"1536x1024"` + The unique identifier of the prompt template to use. - - `:auto` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `class LocalShell` + 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 tool that allows the model to execute shell commands in a local environment. + - `String = String` - - `type: :local_shell` + - `class BetaResponseInputText` - The type of the local shell tool. Always `local_shell`. + A text input to the model. - - `:local_shell` + - `class BetaResponseInputImage` - - `class BetaFunctionShellTool` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A tool that allows the model to execute shell commands. + - `class BetaResponseInputFile` - - `type: :shell` + A file input to the model. - The type of the shell tool. Always `shell`. + - `version: String` - - `:shell` + Optional version of the prompt template. - - `allowed_callers: Array[:direct | :programmatic]` + - `prompt_cache_key: String` - The tool invocation context(s). + 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). - - `:direct` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `:programmatic` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `mode: :implicit | :explicit` - - `class BetaContainerAuto` + Whether implicit prompt-cache breakpoints were enabled. - - `type: :container_auto` + - `:implicit` - Automatically creates a container for this request + - `:explicit` - - `:container_auto` + - `ttl: :"30m"` - - `file_ids: Array[String]` + The minimum lifetime applied to each cache breakpoint. - An optional list of uploaded files to make available to your code. + - `:"30m"` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `prompt_cache_retention: :in_memory | :"24h"` - The memory limit for the container. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `:"1g"` + 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. - - `:"4g"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `:"16g"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `:"64g"` + - `:in_memory` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:"24h"` - Network access policy for the container. + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - - `class BetaContainerNetworkPolicyDisabled` + **gpt-5 and o-series models only** - - `class BetaContainerNetworkPolicyAllowlist` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `context: :auto | :current_turn | :all_turns` - An optional list of skills referenced by id or inline data. + 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. - - `class BetaSkillReference` + - `:auto` - - `skill_id: String` + - `:current_turn` - The ID of the referenced skill. + - `:all_turns` - - `type: :skill_reference` + - `effort: :none | :minimal | :low | 4 more` - References a skill created with the /v1/skills endpoint. + 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. - - `:skill_reference` + - `:none` - - `version: String` + - `:minimal` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `:low` - - `class BetaInlineSkill` + - `:medium` - - `description: String` + - `:high` - The description of the skill. + - `:xhigh` - - `name: String` + - `:max` - The name of the skill. + - `generate_summary: :auto | :concise | :detailed` - - `source: BetaInlineSkillSource` + **Deprecated:** use `summary` instead. - Inline skill payload + 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`. - - `data: String` + - `:auto` - Base64-encoded skill zip bundle. + - `:concise` - - `media_type: :"application/zip"` + - `:detailed` - The media type of the inline skill payload. Must be `application/zip`. + - `mode: String | :standard | :pro` - - `:"application/zip"` + Controls the reasoning execution mode for the request. - - `type: :base64` + When returned on a response, this is the effective execution mode. - The type of the inline skill source. Must be `base64`. + - `String = String` - - `:base64` + - `Mode = :standard | :pro` - - `type: :inline` + Controls the reasoning execution mode for the request. - Defines an inline skill for this request. + When returned on a response, this is the effective execution mode. - - `:inline` + - `:standard` - - `class BetaLocalEnvironment` + - `:pro` - - `type: :local` + - `summary: :auto | :concise | :detailed` - Use a local computer environment. + 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`. - - `:local` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `skills: Array[BetaLocalSkill]` + - `:auto` - An optional list of skills. + - `:concise` - - `description: String` + - `:detailed` - The description of the skill. + - `safety_identifier: String` - - `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 name of the skill. + - `service_tier: :auto | :default | :flex | 2 more` - - `path: String` + Specifies the processing type used for serving the request. - The path to the directory containing the skill. + - 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'. - - `class BetaContainerReference` + 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. - - `container_id: String` + - `:auto` - The ID of the referenced container. + - `:default` - - `type: :container_reference` + - `:flex` - References a container created with the /v1/containers endpoint + - `:scale` - - `:container_reference` + - `:priority` - - `class BetaCustomTool` + - `status: BetaResponseStatus` - 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 status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `name: String` + - `:completed` - 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`. + - `:cancelled` - - `:custom` + - `:queued` - - `allowed_callers: Array[:direct | :programmatic]` + - `:incomplete` - The tool invocation context(s). + - `text: BetaResponseTextConfig` - - `:direct` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `:programmatic` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `defer_loading: bool` + - `format_: BetaResponseFormatTextConfig` - Whether this tool should be deferred and discovered via tool search. + An object specifying the format that the model must output. - - `description: 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 description of the custom tool, used to provide more context. + The default format is `{ "type": "text" }` with no additional options. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + **Not recommended for gpt-4o and newer models:** - The input format for the custom tool. Default is unconstrained text. + 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. - `class Text` - Unconstrained free-form text. + Default response format. Used to generate text responses. - `type: :text` - Unconstrained text format. Always `text`. + The type of response format being defined. Always `text`. - `:text` - - `class Grammar` + - `class BetaResponseFormatTextJSONSchemaConfig` - A grammar defined by the user. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `definition: String` + - `name: String` - The grammar definition. + 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. - - `syntax: :lark | :regex` + - `schema: Hash[Symbol, untyped]` - The syntax of the grammar definition. One of `lark` or `regex`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:lark` + - `type: :json_schema` - - `:regex` + The type of response format being defined. Always `json_schema`. - - `type: :grammar` + - `:json_schema` - Grammar format. Always `grammar`. + - `description: String` - - `:grammar` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaNamespaceTool` + - `strict: bool` - Groups function/custom tools under a shared namespace. + 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). - - `description: String` + - `class JSONObject` - A description of the namespace shown to 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. - - `name: String` + - `type: :json_object` - The namespace name used in tool calls (for example, `crm`). + The type of response format being defined. Always `json_object`. - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `:json_object` - The function/custom tools available inside this namespace. + - `verbosity: :low | :medium | :high` - - `class Function` + 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`. - - `name: String` + - `:low` - - `type: :function` + - `:medium` - - `:function` + - `:high` - - `allowed_callers: Array[:direct | :programmatic]` + - `top_logprobs: Integer` - The tool invocation context(s). + 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. - - `:direct` + - `truncation: :auto | :disabled` - - `:programmatic` + The truncation strategy to use for the model response. - - `defer_loading: bool` + - `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. - Whether this function should be deferred and discovered via tool search. + - `:auto` - - `description: String` + - `:disabled` - - `output_schema: Hash[Symbol, untyped]` + - `usage: BetaResponseUsage` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `parameters: untyped` + - `input_tokens: Integer` - - `strict: bool` + The number of input tokens. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - - `class BetaCustomTool` + A detailed breakdown of the input tokens. - 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) + - `cache_write_tokens: Integer` - - `type: :namespace` + The number of input tokens that were written to the cache. - The type of the tool. Always `namespace`. + - `cached_tokens: Integer` - - `:namespace` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `class BetaToolSearchTool` + - `output_tokens: Integer` - Hosted or BYOT tool search configuration for deferred tools. + The number of output tokens. - - `type: :tool_search` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - The type of the tool. Always `tool_search`. + A detailed breakdown of the output tokens. - - `:tool_search` + - `reasoning_tokens: Integer` - - `description: String` + The number of reasoning tokens. - Description shown to the model for a client-executed tool search tool. + - `total_tokens: Integer` - - `execution: :server | :client` + The total number of tokens used. - Whether tool search is executed by the server or by the client. + - `user: String` - - `:server` + 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). - - `:client` + - `sequence_number: Integer` - - `parameters: untyped` + The sequence number for this event. - Parameter schema for a client-executed tool search tool. + - `type: :"response.completed"` - - `class BetaWebSearchPreviewTool` + The type of the event. Always `response.completed`. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `:"response.completed"` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `agent: Agent{ 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: Array[:text | :image]` +### Beta Response Computer Tool Call - - `:text` +- `class BetaResponseComputerToolCall` - - `: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. - - `search_context_size: :low | :medium | :high` + - `id: String` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The unique ID of the computer call. - - `:low` + - `call_id: String` - - `:medium` + An identifier used when responding to the tool call with output. - - `:high` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `user_location: UserLocation{ type, city, country, 2 more}` + The pending safety checks for the computer call. - The user's location. + - `id: String` - - `type: :approximate` + The ID of the pending safety check. - The type of location approximation. Always `approximate`. + - `code: String` - - `:approximate` + The type of the pending safety check. - - `city: String` + - `message: String` - Free text input for the city of the user, e.g. `San Francisco`. + Details about the pending safety check. - - `country: String` + - `status: :in_progress | :completed | :incomplete` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `region: String` + - `:in_progress` - Free text input for the region of the user, e.g. `California`. + - `:completed` - - `timezone: String` + - `:incomplete` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: :computer_call` - - `class BetaApplyPatchTool` + The type of the computer call. Always `computer_call`. - Allows the assistant to create, delete, or update files using unified diffs. + - `:computer_call` - - `type: :apply_patch` + - `action: BetaComputerAction` - The type of the tool. Always `apply_patch`. + A click action. - - `:apply_patch` + - `class Click` - - `allowed_callers: Array[:direct | :programmatic]` + A click action. - The tool invocation context(s). + - `button: :left | :right | :wheel | 2 more` - - `:direct` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `:programmatic` + - `:left` - - `type: :tool_search_output` + - `:right` - The item type. Always `tool_search_output`. + - `:wheel` - - `:tool_search_output` + - `:back` - - `id: String` + - `:forward` - The unique ID of this tool search output. + - `type: :click` - - `agent: Agent{ agent_name}` + Specifies the event type. For a click action, this property is always `click`. - The agent that produced this item. + - `:click` - - `agent_name: String` + - `x: Integer` - The canonical name of the agent that produced this item. + The x-coordinate where the click occurred. - - `call_id: String` + - `y_: Integer` - The unique ID of the tool search call generated by the model. + The y-coordinate where the click occurred. - - `execution: :server | :client` + - `keys: Array[String]` - Whether tool search was executed by the server or by the client. + The keys being held while clicking. - - `:server` + - `class DoubleClick` - - `:client` + A double click action. - - `status: :in_progress | :completed | :incomplete` + - `keys: Array[String]` - The status of the tool search output. + The keys being held while double-clicking. - - `:in_progress` + - `type: :double_click` - - `:completed` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `:incomplete` + - `:double_click` - - `class AdditionalTools` + - `x: Integer` - - `role: :developer` + The x-coordinate where the double click occurred. - The role that provided the additional tools. Only `developer` is supported. + - `y_: Integer` - - `:developer` + The y-coordinate where the double click occurred. - - `tools: Array[BetaTool]` + - `class Drag` - A list of additional tools made available at this item. + A drag action. - - `class BetaFunctionTool` + - `path: Array[Path{ x, y_}]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `class BetaFileSearchTool` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - 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). + - `x: Integer` - - `class BetaComputerTool` + The x-coordinate. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `y_: Integer` - - `class BetaComputerUsePreviewTool` + The y-coordinate. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :drag` - - `class BetaWebSearchTool` + Specifies the event type. For a drag action, this property is always set to `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). + - `:drag` - - `class Mcp` + - `keys: Array[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 keys being held while dragging the mouse. - - `class CodeInterpreter` + - `class Keypress` - A tool that runs Python code to help generate a response to a prompt. + A collection of keypresses the model would like to perform. - - `class ProgrammaticToolCalling` + - `keys: Array[String]` - - `class ImageGeneration` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A tool that generates images using the GPT image models. + - `type: :keypress` - - `class LocalShell` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - A tool that allows the model to execute shell commands in a local environment. + - `:keypress` - - `class BetaFunctionShellTool` + - `class Move` - A tool that allows the model to execute shell commands. + A mouse move action. - - `class BetaCustomTool` + - `type: :move` - 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) + Specifies the event type. For a move action, this property is always set to `move`. - - `class BetaNamespaceTool` + - `:move` - Groups function/custom tools under a shared namespace. + - `x: Integer` - - `class BetaToolSearchTool` + The x-coordinate to move to. - Hosted or BYOT tool search configuration for deferred tools. + - `y_: Integer` - - `class BetaWebSearchPreviewTool` + The y-coordinate to move to. - 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). + - `keys: Array[String]` - - `class BetaApplyPatchTool` + The keys being held while moving the mouse. - Allows the assistant to create, delete, or update files using unified diffs. + - `class Screenshot` - - `type: :additional_tools` + A screenshot action. - The item type. Always `additional_tools`. + - `type: :screenshot` - - `:additional_tools` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `id: String` + - `:screenshot` - The unique ID of this additional tools item. + - `class Scroll` - - `agent: Agent{ agent_name}` + A scroll action. - The agent that produced this item. + - `scroll_x: Integer` - - `agent_name: String` + The horizontal scroll distance. - The canonical name of the agent that produced this item. + - `scroll_y: Integer` - - `class BetaResponseReasoningItem` + The vertical scroll distance. - 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: :scroll` - - `id: String` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The unique identifier of the reasoning content. + - `:scroll` - - `summary: Array[Summary{ text, type}]` + - `x: Integer` - Reasoning summary content. + The x-coordinate where the scroll occurred. - - `text: String` + - `y_: Integer` - A summary of the reasoning output from the model so far. + The y-coordinate where the scroll occurred. - - `type: :summary_text` + - `keys: Array[String]` - The type of the object. Always `summary_text`. + The keys being held while scrolling. - - `:summary_text` + - `class Type` - - `type: :reasoning` + An action to type in text. - The type of the object. Always `reasoning`. + - `text: String` - - `:reasoning` + The text to type. - - `agent: Agent{ agent_name}` + - `type: :type` - The agent that produced this item. + Specifies the event type. For a type action, this property is always set to `type`. - - `agent_name: String` + - `:type` - The canonical name of the agent that produced this item. + - `class Wait` - - `content: Array[Content{ text, type}]` + A wait action. - Reasoning text content. + - `type: :wait` - - `text: String` + Specifies the event type. For a wait action, this property is always set to `wait`. - The reasoning text from the model. + - `:wait` - - `type: :reasoning_text` + - `actions: BetaComputerActionList` - The type of the reasoning text. Always `reasoning_text`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `:reasoning_text` + - `class Click` - - `encrypted_content: String` + A click action. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `class DoubleClick` - - `status: :in_progress | :completed | :incomplete` + A double click action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class Drag` - - `:in_progress` + A drag action. - - `:completed` + - `class Keypress` - - `:incomplete` + A collection of keypresses the model would like to perform. - - `class BetaResponseCompactionItemParam` + - `class Move` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A mouse move action. - - `encrypted_content: String` + - `class Screenshot` - The encrypted content of the compaction summary. + A screenshot action. - - `type: :compaction` + - `class Scroll` - The type of the item. Always `compaction`. + A scroll action. - - `:compaction` + - `class Type` - - `id: String` + An action to type in text. - The ID of the compaction item. + - `class Wait` + + A wait action. - `agent: Agent{ agent_name}` @@ -41692,1081 +51488,1104 @@ Compact a response The canonical name of the agent that produced this item. - - `class ImageGenerationCall` +### Beta Response Computer Tool Call Output Item - An image generation request made by the model. +- `class BetaResponseComputerToolCallOutputItem` - `id: String` - The unique ID of the image generation call. + The unique ID of the computer call tool output. - - `result: String` + - `call_id: String` - The generated image encoded in base64. + The ID of the computer tool call that produced the output. - - `status: :in_progress | :completed | :generating | :failed` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The status of the image generation call. + A computer screenshot image used with the computer use tool. - - `:in_progress` + - `type: :computer_screenshot` - - `:completed` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:generating` + - `:computer_screenshot` - - `:failed` + - `file_id: String` - - `type: :image_generation_call` + The identifier of an uploaded file that contains the screenshot. - The type of the image generation call. Always `image_generation_call`. + - `image_url: String` - - `:image_generation_call` + The URL of the screenshot image. + + - `status: :completed | :incomplete | :failed | :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` - - `agent: Agent{ agent_name}` + - `:in_progress` - The agent that produced this item. + - `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` - - `class BetaResponseCodeInterpreterToolCall` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - A tool call to run code. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: String` - The unique ID of the code interpreter tool call. + The ID of the pending safety check. - `code: String` - The code to run, or null if not available. - - - `container_id: String` - - The ID of the container used to run the code. + The type of the pending safety check. - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `message: String` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Details about the pending safety check. - - `class Logs` + - `agent: Agent{ agent_name}` - The logs output from the code interpreter. + The agent that produced this item. - - `logs: String` + - `agent_name: String` - The logs output from the code interpreter. + The canonical name of the agent that produced this item. - - `type: :logs` + - `created_by: String` - The type of the output. Always `logs`. + The identifier of the actor that created the item. - - `:logs` +### Beta Response Computer Tool Call Output Screenshot - - `class Image` +- `class BetaResponseComputerToolCallOutputScreenshot` - The image output from the code interpreter. + A computer screenshot image used with the computer use tool. - - `type: :image` + - `type: :computer_screenshot` - The type of the output. Always `image`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:image` + - `:computer_screenshot` - - `url: String` + - `file_id: String` - The URL of the image output from the code interpreter. + The identifier of an uploaded file that contains the screenshot. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `image_url: String` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The URL of the screenshot image. - - `:in_progress` +### Beta Response Container Reference - - `:completed` +- `class BetaResponseContainerReference` - - `:incomplete` + Represents a container created with /v1/containers. - - `:interpreting` + - `container_id: String` - - `:failed` + - `type: :container_reference` - - `type: :code_interpreter_call` + The environment type. Always `container_reference`. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `:container_reference` - - `:code_interpreter_call` +### Beta Response Content - - `agent: Agent{ agent_name}` +- `BetaResponseContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile | 3 more` - The agent that produced this item. + Multi-modal input and output contents. - - `agent_name: String` + - `class BetaResponseInputText` - The canonical name of the agent that produced this item. + A text input to the model. - - `class LocalShellCall` + - `text: String` - A tool call to run a command on the local shell. + The text input to the model. - - `id: String` + - `type: :input_text` - The unique ID of the local shell call. + The type of the input item. Always `input_text`. - - `action: Action{ command, env, type, 3 more}` + - `:input_text` - Execute a shell command on the server. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `command: Array[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 command to run. + - `mode: :explicit` - - `env: Hash[Symbol, String]` + The breakpoint mode. Always `explicit`. - Environment variables to set for the command. + - `:explicit` - - `type: :exec` + - `class BetaResponseInputImage` - The type of the local shell action. Always `exec`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:exec` + - `detail: :low | :high | :auto | :original` - - `timeout_ms: Integer` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Optional timeout in milliseconds for the command. + - `:low` - - `user: String` + - `:high` - Optional user to run the command as. + - `:auto` - - `working_directory: String` + - `:original` - Optional working directory to run the command in. + - `type: :input_image` - - `call_id: String` + The type of the input item. Always `input_image`. - The unique ID of the local shell tool call generated by the model. + - `:input_image` - - `status: :in_progress | :completed | :incomplete` + - `file_id: String` - The status of the local shell call. + The ID of the file to be sent to the model. - - `:in_progress` + - `image_url: 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: PromptCacheBreakpoint{ mode}` - - `type: :local_shell_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. - The type of the local shell call. Always `local_shell_call`. + - `mode: :explicit` - - `:local_shell_call` + The breakpoint mode. Always `explicit`. - - `agent: Agent{ agent_name}` + - `:explicit` - The agent that produced this item. + - `class BetaResponseInputFile` - - `agent_name: String` + A file input to the model. - The canonical name of the agent that produced this item. + - `type: :input_file` - - `class LocalShellCallOutput` + The type of the input item. Always `input_file`. - The output of a local shell tool call. + - `:input_file` - - `id: String` + - `detail: :auto | :low | :high` - The unique ID of the local shell tool call generated by 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`. - - `output: String` + - `:auto` - A JSON string of the output of the local shell tool call. + - `:low` - - `type: :local_shell_call_output` + - `:high` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `file_data: String` - - `:local_shell_call_output` + The content of the file to be sent to the model. - - `agent: Agent{ agent_name}` + - `file_id: String` - The agent that produced this item. + The ID of the file to be sent to the model. - - `agent_name: String` + - `file_url: String` - The canonical name of the agent that produced this item. + The URL of the file to be sent to the model. - - `status: :in_progress | :completed | :incomplete` + - `filename: String` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The name of the file to be sent to the model. - - `:in_progress` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` - - `class ShellCall` + The breakpoint mode. Always `explicit`. - A tool representing a request to execute one or more shell commands. + - `:explicit` - - `action: Action{ commands, max_output_length, timeout_ms}` + - `class BetaResponseOutputText` - The shell commands and limits that describe how to run the tool call. + A text output from the model. - - `commands: Array[String]` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - Ordered shell commands for the execution environment to run. + The annotations of the text output. - - `max_output_length: Integer` + - `class FileCitation` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + A citation to a file. - - `timeout_ms: Integer` + - `file_id: String` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The ID of the file. - - `call_id: String` + - `filename: String` - The unique ID of the shell tool call generated by the model. + The filename of the file cited. - - `type: :shell_call` + - `index: Integer` - The type of the item. Always `shell_call`. + The index of the file in the list of files. - - `:shell_call` + - `type: :file_citation` - - `id: String` + The type of the file citation. Always `file_citation`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `:file_citation` - - `agent: Agent{ agent_name}` + - `class URLCitation` - The agent that produced this item. + A citation for a web resource used to generate a model response. - - `agent_name: String` + - `end_index: Integer` - The canonical name of the agent that produced this item. + The index of the last character of the URL citation in the message. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `start_index: Integer` - The execution context that produced this tool call. + The index of the first character of the URL citation in the message. - - `class Direct` + - `title: String` - - `type: :direct` + The title of the web resource. - The caller type. Always `direct`. + - `type: :url_citation` - - `:direct` + The type of the URL citation. Always `url_citation`. - - `class Program` + - `:url_citation` - - `caller_id: String` + - `url: String` - The call ID of the program item that produced this tool call. + The URL of the web resource. - - `type: :program` + - `class ContainerFileCitation` - The caller type. Always `program`. + A citation for a container file used to generate a model response. - - `:program` + - `container_id: String` - - `environment: BetaLocalEnvironment | BetaContainerReference` + The ID of the container file. - The environment to execute the shell commands in. + - `end_index: Integer` - - `class BetaLocalEnvironment` + The index of the last character of the container file citation in the message. - - `class BetaContainerReference` + - `file_id: String` - - `status: :in_progress | :completed | :incomplete` + The ID of the file. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `filename: String` - - `:in_progress` + The filename of the container file cited. - - `:completed` + - `start_index: Integer` - - `:incomplete` + The index of the first character of the container file citation in the message. - - `class ShellCallOutput` + - `type: :container_file_citation` - The streamed output items emitted by a shell tool call. + The type of the container file citation. Always `container_file_citation`. - - `call_id: String` + - `:container_file_citation` - The unique ID of the shell tool call generated by the model. + - `class FilePath` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + A path to a file. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `file_id: String` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + The ID of the file. - The exit or timeout outcome associated with this shell call. + - `index: Integer` - - `class Timeout` + The index of the file in the list of files. - Indicates that the shell call exceeded its configured time limit. + - `type: :file_path` - - `type: :timeout` + The type of the file path. Always `file_path`. - The outcome type. Always `timeout`. + - `:file_path` - - `:timeout` + - `text: String` - - `class Exit` + The text output from the model. - Indicates that the shell commands finished and returned an exit code. + - `type: :output_text` - - `exit_code: Integer` + The type of the output text. Always `output_text`. - The exit code returned by the shell process. + - `:output_text` - - `type: :exit` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - The outcome type. Always `exit`. + - `token: String` - - `:exit` + - `bytes: Array[Integer]` - - `stderr: String` + - `logprob: Float` - Captured stderr output for the shell call. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `stdout: String` + - `token: String` - Captured stdout output for the shell call. + - `bytes: Array[Integer]` - - `type: :shell_call_output` + - `logprob: Float` - The type of the item. Always `shell_call_output`. + - `class BetaResponseOutputRefusal` - - `:shell_call_output` + A refusal from the model. - - `id: String` + - `refusal: String` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The refusal explanation from the model. - - `agent: Agent{ agent_name}` + - `type: :refusal` - The agent that produced this item. + The type of the refusal. Always `refusal`. - - `agent_name: String` + - `:refusal` - The canonical name of the agent that produced this item. + - `class ReasoningText` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Reasoning text from the model. - The execution context that produced this tool call. + - `text: String` - - `class Direct` + 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` - - `class Program` +### Beta Response Content Part Added Event - - `caller_id: String` +- `class BetaResponseContentPartAddedEvent` - The call ID of the program item that produced this tool call. + Emitted when a new content part is added. - - `type: :program` + - `content_index: Integer` - The caller type. Always `program`. + The index of the content part that was added. - - `:program` + - `item_id: String` - - `max_output_length: Integer` + The ID of the output item that the content part was added to. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `output_index: Integer` - - `status: :in_progress | :completed | :incomplete` + The index of the output item that the content part was added to. - The status of the shell call output. + - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` - - `:in_progress` + The content part that was added. - - `:completed` + - `class BetaResponseOutputText` - - `:incomplete` + A text output from the model. - - `class ApplyPatchCall` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - A tool call representing a request to create, delete, or update files using diff patches. + The annotations of the text output. - - `call_id: String` + - `class FileCitation` - The unique ID of the apply patch tool call generated by the model. + A citation to a file. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `file_id: String` - The specific create, delete, or update instruction for the apply_patch tool call. + The ID of the file. - - `class CreateFile` + - `filename: String` - Instruction for creating a new file via the apply_patch tool. + The filename of the file cited. - - `diff: String` + - `index: Integer` - Unified diff content to apply when creating the file. + The index of the file in the list of files. - - `path: String` + - `type: :file_citation` - Path of the file to create relative to the workspace root. + The type of the file citation. Always `file_citation`. - - `type: :create_file` + - `:file_citation` - The operation type. Always `create_file`. + - `class URLCitation` - - `:create_file` + A citation for a web resource used to generate a model response. - - `class DeleteFile` + - `end_index: Integer` - Instruction for deleting an existing file via the apply_patch tool. + The index of the last character of the URL citation in the message. - - `path: String` + - `start_index: Integer` - Path of the file to delete relative to the workspace root. + The index of the first character of the URL citation in the message. - - `type: :delete_file` + - `title: String` - The operation type. Always `delete_file`. + The title of the web resource. - - `:delete_file` + - `type: :url_citation` - - `class UpdateFile` + The type of the URL citation. Always `url_citation`. - Instruction for updating an existing file via the apply_patch tool. + - `:url_citation` - - `diff: String` + - `url: String` - Unified diff content to apply to the existing file. + The URL of the web resource. - - `path: String` + - `class ContainerFileCitation` - Path of the file to update relative to the workspace root. + A citation for a container file used to generate a model response. - - `type: :update_file` + - `container_id: String` - The operation type. Always `update_file`. + The ID of the container file. - - `:update_file` + - `end_index: Integer` - - `status: :in_progress | :completed` + The index of the last character of the container file citation in the message. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `file_id: String` - - `:in_progress` + The ID of the file. - - `:completed` + - `filename: String` - - `type: :apply_patch_call` + The filename of the container file cited. - The type of the item. Always `apply_patch_call`. + - `start_index: Integer` - - `:apply_patch_call` + The index of the first character of the container file citation in the message. - - `id: String` + - `type: :container_file_citation` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the container file citation. Always `container_file_citation`. - - `agent: Agent{ agent_name}` + - `:container_file_citation` - The agent that produced this item. + - `class FilePath` - - `agent_name: String` + A path to a file. - The canonical name of the agent that produced this item. + - `file_id: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The ID of the file. - The execution context that produced this tool call. + - `index: Integer` - - `class Direct` + The index of the file in the list of files. - - `type: :direct` + - `type: :file_path` - The caller type. Always `direct`. + The type of the file path. Always `file_path`. - - `:direct` + - `:file_path` - - `class Program` + - `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`. - The caller type. Always `program`. + - `:output_text` - - `:program` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `class ApplyPatchCallOutput` + - `token: String` - The streamed output emitted by an apply patch tool call. + - `bytes: Array[Integer]` - - `call_id: String` + - `logprob: Float` - The unique ID of the apply patch tool call generated by the model. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `status: :completed | :failed` + - `token: String` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `bytes: Array[Integer]` - - `:completed` + - `logprob: Float` - - `:failed` + - `class BetaResponseOutputRefusal` - - `type: :apply_patch_call_output` + A refusal from the model. - The type of the item. Always `apply_patch_call_output`. + - `refusal: String` - - `:apply_patch_call_output` + The refusal explanation from the model. - - `id: String` + - `type: :refusal` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The type of the refusal. Always `refusal`. - - `agent: Agent{ agent_name}` + - `:refusal` - The agent that produced this item. + - `class ReasoningText` - - `agent_name: String` + Reasoning text from the model. - The canonical name of the agent that produced this item. + - `text: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The reasoning text from the model. - The execution context that produced this tool call. + - `type: :reasoning_text` - - `class Direct` + The type of the reasoning text. Always `reasoning_text`. - - `type: :direct` + - `:reasoning_text` - The caller type. Always `direct`. + - `sequence_number: Integer` - - `:direct` + The sequence number of this event. - - `class Program` + - `type: :"response.content_part.added"` - - `caller_id: String` + The type of the event. Always `response.content_part.added`. - The call ID of the program item that produced this tool call. + - `:"response.content_part.added"` - - `type: :program` + - `agent: Agent{ agent_name}` - The caller type. Always `program`. + The agent that owns this multi-agent streaming event. - - `:program` + - `agent_name: String` - - `output: String` + The canonical name of the agent that produced this item. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). +### Beta Response Content Part Done Event - - `class McpListTools` +- `class BetaResponseContentPartDoneEvent` - A list of tools available on an MCP server. + Emitted when a content part is done. - - `id: String` + - `content_index: Integer` - The unique ID of the list. + The index of the content part that is done. - - `server_label: String` + - `item_id: String` - The label of the MCP server. + The ID of the output item that the content part was added to. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `output_index: Integer` - The tools available on the server. + The index of the output item that the content part was added to. - - `input_schema: untyped` + - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` - The JSON schema describing the tool's input. + The content part that is done. - - `name: String` + - `class BetaResponseOutputText` - The name of the tool. + A text output from the model. - - `annotations: untyped` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - Additional annotations about the tool. + The annotations of the text output. - - `description: String` + - `class FileCitation` - The description of the tool. + A citation to a file. - - `type: :mcp_list_tools` + - `file_id: String` - The type of the item. Always `mcp_list_tools`. + The ID of the file. - - `:mcp_list_tools` + - `filename: String` - - `agent: Agent{ agent_name}` + The filename of the file cited. - The agent that produced this item. + - `index: Integer` - - `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` - - `error: String` + The type of the file citation. Always `file_citation`. - Error message if the server could not list tools. + - `:file_citation` - - `class McpApprovalRequest` + - `class URLCitation` - A request for human approval of a tool invocation. + A citation for a web resource used to generate a model response. - - `id: String` + - `end_index: Integer` - The unique ID of the approval request. + The index of the last character of the URL citation in the message. - - `arguments: String` + - `start_index: Integer` - A JSON string of arguments for the tool. + The index of the first character of the URL citation in the message. - - `name: String` + - `title: String` - The name of the tool to run. + The title of the web resource. - - `server_label: String` + - `type: :url_citation` - The label of the MCP server making the request. + The type of the URL citation. Always `url_citation`. - - `type: :mcp_approval_request` + - `:url_citation` - The type of the item. Always `mcp_approval_request`. + - `url: String` - - `:mcp_approval_request` + The URL of the web resource. - - `agent: Agent{ agent_name}` + - `class ContainerFileCitation` - The agent that produced this item. + A citation for a container file used to generate a model response. - - `agent_name: String` + - `container_id: String` - The canonical name of the agent that produced this item. + The ID of the container file. - - `class McpApprovalResponse` + - `end_index: Integer` - A response to an MCP approval request. + The index of the last character of the container file citation in the message. - - `approval_request_id: String` + - `file_id: String` - The ID of the approval request being answered. + The ID of the file. - - `approve: bool` + - `filename: String` - Whether the request was approved. + The filename of the container file cited. - - `type: :mcp_approval_response` + - `start_index: Integer` - The type of the item. Always `mcp_approval_response`. + The index of the first character of the container file citation in the message. - - `:mcp_approval_response` + - `type: :container_file_citation` - - `id: String` + The type of the container file citation. Always `container_file_citation`. - The unique ID of the approval response + - `:container_file_citation` - - `agent: Agent{ agent_name}` + - `class FilePath` - 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. - - `reason: String` + - `index: Integer` - Optional reason for the decision. + The index of the file in the list of files. - - `class McpCall` + - `type: :file_path` - An invocation of a tool on an MCP server. + The type of the file path. Always `file_path`. - - `id: String` + - `:file_path` - The unique ID of the tool call. + - `text: String` - - `arguments: String` + The text output from the model. - A JSON string of the arguments passed to the tool. + - `type: :output_text` - - `name: String` + The type of the output text. Always `output_text`. - The name of the tool that was run. + - `:output_text` - - `server_label: String` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - The label of the MCP server running the tool. + - `token: String` - - `type: :mcp_call` + - `bytes: Array[Integer]` - The type of the item. Always `mcp_call`. + - `logprob: Float` - - `:mcp_call` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `agent: Agent{ agent_name}` + - `token: String` - The agent that produced this item. + - `bytes: Array[Integer]` - - `agent_name: String` + - `logprob: Float` - The canonical name of the agent that produced this item. + - `class BetaResponseOutputRefusal` - - `approval_request_id: String` + A refusal from the model. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `refusal: String` - - `error: String` + The refusal explanation from the model. - The error from the tool call, if any. + - `type: :refusal` - - `output: String` + The type of the refusal. Always `refusal`. - The output from the tool call. + - `:refusal` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `class ReasoningText` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Reasoning text from the model. - - `:in_progress` + - `text: String` - - `:completed` + The reasoning text from the model. - - `:incomplete` + - `type: :reasoning_text` - - `:calling` + The type of the reasoning text. Always `reasoning_text`. - - `:failed` + - `:reasoning_text` - - `class BetaResponseCustomToolCallOutput` + - `sequence_number: Integer` - The output of a custom tool call from your code, being sent back to the model. + The sequence number of this event. - - `call_id: String` + - `type: :"response.content_part.done"` - The call ID, used to map this custom tool call output to a custom tool call. + The type of the event. Always `response.content_part.done`. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:"response.content_part.done"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `agent: Agent{ agent_name}` - - `String = String` + The agent that owns this multi-agent streaming event. - A string of the output of the custom tool call. + - `agent_name: String` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The canonical name of the agent that produced this item. - Text, image, or file output of the custom tool call. +### Beta Response Conversation Param - - `class BetaResponseInputText` +- `class BetaResponseConversationParam` - A text input to the model. + The conversation that this response belongs to. - - `class BetaResponseInputImage` + - `id: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the conversation. - - `class BetaResponseInputFile` +### Beta Response Created Event - A file input to the model. +- `class BetaResponseCreatedEvent` - - `type: :custom_tool_call_output` + An event that is emitted when a response is created. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `response: BetaResponse` - - `:custom_tool_call_output` + The response that was created. - `id: String` - The unique ID of the custom tool call output in the OpenAI platform. + Unique identifier for this Response. - - `agent: Agent{ agent_name}` + - `created_at: Float` - 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. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - The execution context that produced this tool call. + The error code for the response. - - `class Direct` + - `:server_error` - - `type: :direct` + - `:rate_limit_exceeded` - The caller type. Always `direct`. + - `:invalid_prompt` - - `:direct` + - `:bio_policy` - - `class Program` + - `:vector_store_timeout` - - `caller_id: String` + - `:invalid_image` - The call ID of the program item that produced this tool call. + - `:invalid_image_format` - - `type: :program` + - `:invalid_base64_image` - The caller type. Always `program`. + - `:invalid_image_url` - - `:program` + - `:image_too_large` - - `class BetaResponseCustomToolCall` + - `:image_too_small` - A call to a custom tool created by the model. + - `:image_parse_error` - - `call_id: String` + - `:image_content_policy_violation` - An identifier used to map this custom tool call to a tool call output. + - `:invalid_image_mode` - - `input: String` + - `:image_file_too_large` - The input for the custom tool call generated by the model. + - `:unsupported_image_media_type` - - `name: String` + - `:empty_image_file` - The name of the custom tool being called. + - `:failed_to_download_image` - - `type: :custom_tool_call` + - `:image_file_not_found` - The type of the custom tool call. Always `custom_tool_call`. + - `message: String` - - `:custom_tool_call` + A human-readable description of the error. - - `id: String` + - `incomplete_details: IncompleteDetails{ reason}` - The unique ID of the custom tool call in the OpenAI platform. + Details about why the response is incomplete. - - `agent: Agent{ agent_name}` + - `reason: :max_output_tokens | :content_filter` - The agent that produced this item. + The reason why the response is incomplete. - - `agent_name: String` + - `:max_output_tokens` - The canonical name of the agent that produced this item. + - `:content_filter` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `instructions: String | Array[BetaResponseInputItem]` - The execution context that produced this tool call. + A system (or developer) message inserted into the model's context. - - `class Direct` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `type: :direct` + - `String = String` - - `:direct` + A text input to the model, equivalent to a text input with the + `developer` role. - - `class Program` + - `InputItemList = Array[BetaResponseInputItem]` - - `caller_id: String` + A list of one or many input items to the model, containing + different content types. - The call ID of the program item that produced this tool call. + - `class BetaEasyInputMessage` - - `type: :program` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `:program` + - `content: String | BetaResponseInputMessageContentList` - - `namespace: String` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The namespace of the custom tool being called. + - `String = String` - - `class CompactionTrigger` + A text input to the model. - Compacts the current context. Must be the final input item. + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `type: :compaction_trigger` + A list of one or many input items to the model, containing different content + types. - The type of the item. Always `compaction_trigger`. + - `class BetaResponseInputText` - - `:compaction_trigger` + A text input to the model. - - `agent: Agent{ 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`. - - `class ItemReference` + - `:input_text` - An internal identifier for an item to reference. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 item to reference. + - `mode: :explicit` - - `agent: Agent{ agent_name}` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `:explicit` - - `agent_name: String` + - `class BetaResponseInputImage` - 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). - - `type: :item_reference` + - `detail: :low | :high | :auto | :original` - The type of item to reference. Always `item_reference`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:item_reference` + - `:low` - - `class Program` + - `:high` - - `id: String` + - `:auto` - The unique ID of this program item. + - `:original` - - `call_id: String` + - `type: :input_image` - The stable call ID of the program item. + The type of the input item. Always `input_image`. - - `code: String` + - `:input_image` - The JavaScript source executed by programmatic tool calling. + - `file_id: String` - - `fingerprint: String` + The ID of the file to be sent to the model. - Opaque program replay fingerprint that must be round-tripped. + - `image_url: 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 item type. Always `program`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `agent: Agent{ 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. + - `class BetaResponseInputFile` - - `class ProgramOutput` + A file input to the model. - - `id: String` + - `type: :input_file` - The unique ID of this program output item. + The type of the input item. Always `input_file`. - - `call_id: String` + - `:input_file` - The call ID of the program item. + - `detail: :auto | :low | :high` - - `result: 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 result produced by the program item. + - `:auto` - - `status: :completed | :incomplete` + - `:low` - The terminal status of the program output. + - `:high` - - `:completed` + - `file_data: String` - - `:incomplete` + The content of the file to be sent to the model. - - `type: :program_output` + - `file_id: String` - The item type. Always `program_output`. + The ID of the file to be sent to the model. - - `:program_output` + - `file_url: String` - - `agent: Agent{ agent_name}` + The URL of the file to be sent to the model. - The agent that produced this item. + - `filename: 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: PromptCacheBreakpoint{ mode}` -- `instructions: 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. - 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. + - `mode: :explicit` -- `previous_response_id: String` + The breakpoint mode. Always `explicit`. - 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`. + - `:explicit` -- `prompt_cache_key: String` + - `role: :user | :assistant | :system | :developer` - A key to use when reading from or writing to the prompt cache. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. -- `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `:user` - 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. + - `:assistant` - - `mode: :implicit | :explicit` + - `:system` - 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. + - `:developer` - - `:implicit` + - `phase: :commentary | :final_answer` - - `:explicit` + 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. - - `ttl: :"30m"` + - `:commentary` - 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. + - `:final_answer` - - `:"30m"` + - `type: :message` -- `prompt_cache_retention: :in_memory | :"24h"` + The type of the message input. Always `message`. - How long to retain a prompt cache entry created by this request. + - `:message` - - `:in_memory` + - `class Message` - - `:"24h"` + 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. -- `service_tier: :auto | :default | :flex | :priority` + - `content: BetaResponseInputMessageContentList` - The service tier to use for this request. + A list of one or many input items to the model, containing different content + types. - - `:auto` + - `role: :user | :system | :developer` - - `:default` + The role of the message input. One of `user`, `system`, or `developer`. - - `:flex` + - `:user` - - `:priority` + - `:system` -- `betas: Array[:"responses_multi_agent=v1"]` + - `:developer` - - `:"responses_multi_agent=v1"` + - `agent: Agent{ agent_name}` -### Returns + The agent that produced this item. -- `class BetaCompactedResponse` + - `agent_name: String` - - `id: String` + The canonical name of the agent that produced this item. - The unique identifier for the compacted response. + - `status: :in_progress | :completed | :incomplete` - - `created_at: Integer` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unix timestamp (in seconds) when the compacted conversation was created. + - `:in_progress` - - `object: :"response.compaction"` + - `:completed` - The object type. Always `response.compaction`. + - `:incomplete` - - `:"response.compaction"` + - `type: :message` - - `output: Array[BetaResponseOutputItem]` + The type of the message input. Always set to `message`. - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `:message` - `class BetaResponseOutputMessage` @@ -42955,7 +52774,7 @@ Compact a response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -42963,6 +52782,8 @@ Compact a response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -43039,64 +52860,34 @@ Compact a response The text that was retrieved from the file. - - `class BetaResponseFunctionToolCall` + - `class BetaResponseComputerToolCall` - 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](https://platform.openai.com/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` + An identifier used when responding to the tool call with output. - The type of the function tool call. Always `function_call`. + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `:function_call` + The pending safety checks for the computer call. - `id: String` - The unique ID of the function tool call. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. + The ID of the pending safety check. - - `type: :program` + - `code: String` - - `:program` + The type of the pending safety check. - - `namespace: String` + - `message: String` - The namespace of the function to run. + Details about the pending safety check. - `status: :in_progress | :completed | :incomplete` @@ -43109,275 +52900,274 @@ Compact a response - `:incomplete` - - `class BetaResponseFunctionToolCallOutputItem` - - - `id: String` - - The unique ID of the function call tool output. - - - `call_id: String` + - `type: :computer_call` - The unique ID of the function tool call generated by the model. + The type of the computer call. Always `computer_call`. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:computer_call` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `action: BetaComputerAction` - - `String = String` + A click action. - A string of the output of the function call. + - `class Click` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + A click action. - Text, image, or file output of the function call. + - `button: :left | :right | :wheel | 2 more` - - `class BetaResponseInputText` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - A text input to the model. + - `:left` - - `text: String` + - `:right` - The text input to the model. + - `:wheel` - - `type: :input_text` + - `:back` - The type of the input item. Always `input_text`. + - `:forward` - - `:input_text` + - `type: :click` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: Integer` - The breakpoint mode. Always `explicit`. + The x-coordinate where the click occurred. - - `:explicit` + - `y_: Integer` - - `class BetaResponseInputImage` + The y-coordinate where the click occurred. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `keys: Array[String]` - - `detail: :low | :high | :auto | :original` + The keys being held while clicking. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class DoubleClick` - - `:low` + A double click action. - - `:high` + - `keys: Array[String]` - - `:auto` + The keys being held while double-clicking. - - `:original` + - `type: :double_click` - - `type: :input_image` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The type of the input item. Always `input_image`. + - `:double_click` - - `:input_image` + - `x: Integer` - - `file_id: String` + The x-coordinate where the double click occurred. - The ID of the file to be sent to the model. + - `y_: Integer` - - `image_url: String` + The y-coordinate where the double 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. + - `class Drag` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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[Path{ 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: Integer` - - `class BetaResponseInputFile` + The x-coordinate. - A file input to the model. + - `y_: Integer` - - `type: :input_file` + The y-coordinate. - The type of the input item. Always `input_file`. + - `type: :drag` - - `:input_file` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `detail: :auto | :low | :high` + - `:drag` - 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[String]` - - `:auto` + The keys being held while dragging the mouse. - - `:low` + - `class Keypress` - - `:high` + A collection of keypresses the model would like to perform. - - `file_data: String` + - `keys: Array[String]` - The content 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. - - `file_id: String` + - `type: :keypress` - The ID of the file to be sent to the model. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `file_url: String` + - `:keypress` - The URL of the file to be sent to the model. + - `class Move` - - `filename: String` + A mouse move action. - The name of the file to be sent to the model. + - `type: :move` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Specifies the event type. For a move action, this property is always set to `move`. - Marks the exact end of a reusable 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` - - `mode: :explicit` + - `x: Integer` - The breakpoint mode. Always `explicit`. + The x-coordinate to move to. - - `:explicit` + - `y_: Integer` - - `status: :in_progress | :completed | :incomplete` + The y-coordinate to move to. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `keys: Array[String]` - - `:in_progress` + The keys being held while moving the mouse. - - `:completed` + - `class Screenshot` - - `:incomplete` + A screenshot action. - - `type: :function_call_output` + - `type: :screenshot` - The type of the function tool call output. Always `function_call_output`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `:function_call_output` + - `:screenshot` - - `agent: Agent{ agent_name}` + - `class Scroll` - The agent that produced this item. + A scroll action. - - `agent_name: String` + - `scroll_x: Integer` - The canonical name of the agent that produced this item. + The horizontal scroll distance. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `scroll_y: Integer` - The execution context that produced this tool call. + The vertical scroll distance. - - `class Direct` + - `type: :scroll` - - `type: :direct` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The caller type. Always `direct`. + - `:scroll` - - `:direct` + - `x: Integer` - - `class Program` + The x-coordinate where the scroll occurred. - - `caller_id: String` + - `y_: Integer` - The call ID of the program item that produced this tool call. + The y-coordinate where the scroll occurred. - - `type: :program` + - `keys: Array[String]` - The caller type. Always `program`. + The keys being held while scrolling. - - `:program` + - `class Type` - - `created_by: String` + An action to type in text. - The identifier of the actor that created the item. + - `text: String` - - `class AgentMessage` + The text to type. - - `id: String` + - `type: :type` - The unique ID of the agent message. + Specifies the event type. For a type action, this property is always set to `type`. - - `author: String` + - `:type` - The sending agent identity. + - `class Wait` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + A wait action. - Encrypted content sent between agents. + - `type: :wait` - - `class BetaResponseInputText` + Specifies the event type. For a wait action, this property is always set to `wait`. - A text input to the model. + - `:wait` - - `class BetaResponseOutputText` + - `actions: BetaComputerActionList` - A text output from the model. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `class Text` + - `class Click` - A text content. + A click action. - - `text: String` + - `class DoubleClick` - - `type: :text` + A double click action. - - `:text` + - `class Drag` - - `class SummaryText` + A drag action. - A summary text from the model. + - `class Keypress` - - `text: String` + A collection of keypresses the model would like to perform. - A summary of the reasoning output from the model so far. + - `class Move` - - `type: :summary_text` + A mouse move action. - The type of the object. Always `summary_text`. + - `class Screenshot` - - `:summary_text` + A screenshot action. - - `class ReasoningText` + - `class Scroll` - Reasoning text from the model. + A scroll action. - - `text: String` + - `class Type` - The reasoning text from the model. + An action to type in text. - - `type: :reasoning_text` + - `class Wait` - The type of the reasoning text. Always `reasoning_text`. + A wait action. - - `:reasoning_text` + - `agent: Agent{ agent_name}` - - `class BetaResponseOutputRefusal` + The agent that produced this item. - A refusal from the model. + - `agent_name: String` - - `class BetaResponseInputImage` + 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). + - `class ComputerCallOutput` - - `class ComputerScreenshot` + The output of a computer tool call. - A screenshot of a computer. + - `call_id: String` - - `detail: :low | :high | :auto | :original` + The ID of the computer tool call that produced the output. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `:low` + A computer screenshot image used with the computer use tool. - - `:high` + - `type: :computer_screenshot` - - `:auto` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:original` + - `:computer_screenshot` - `file_id: String` @@ -43387,93 +53177,31 @@ Compact a response 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: PromptCacheBreakpoint{ 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` - - - `class BetaResponseInputFile` - - A file input to the model. - - - `class EncryptedContent` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` + - `type: :computer_call_output` - The canonical name of the agent that produced this item. + The type of the computer tool call output. Always `computer_call_output`. - - `class MultiAgentCall` + - `:computer_call_output` - `id: String` - The unique ID of the multi-agent call item. - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action to execute. - - - `:spawn_agent` - - - `:interrupt_agent` - - - `:list_agents` - - - `:send_message` - - - `:followup_task` + The ID of the computer tool call output. - - `:wait_agent` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `arguments: String` + The safety checks reported by the API that have been acknowledged by the developer. - The JSON string of arguments generated for the action. + - `id: String` - - `call_id: String` + The ID of the pending safety check. - The unique ID linking this call to its output. + - `code: String` - - `type: :multi_agent_call` + The type of the pending safety check. - The type of the multi-agent call. Always `multi_agent_call`. + - `message: String` - - `:multi_agent_call` + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -43483,63 +53211,15 @@ Compact a response The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput` - - - `id: String` - - The unique ID of the multi-agent call output item. - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 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[BetaResponseOutputText]` - - Text output returned by the multi-agent action. - - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ 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: Array[Logprob{ 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: :in_progress | :completed | :incomplete` - - `agent: Agent{ 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` - `class BetaResponseFunctionWebSearch` @@ -43645,360 +53325,349 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall` + - `class BetaResponseFunctionToolCall` - 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](https://platform.openai.com/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[PendingSafetyCheck{ 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: String` + The type of the function tool call. Always `function_call`. - The type of the pending safety check. + - `:function_call` - - `message: String` + - `id: String` - Details about the pending safety check. + The unique ID of the function tool call. - - `status: :in_progress | :completed | :incomplete` + - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - `type: :computer_call` + The execution context that produced this tool call. - The type of the computer call. Always `computer_call`. + - `class Direct` - - `:computer_call` + - `type: :direct` - - `action: BetaComputerAction` + - `:direct` - A click action. + - `class Program` - - `class Click` + - `caller_id: String` - A click action. + The call ID of the program item that produced this tool call. - - `button: :left | :right | :wheel | 2 more` + - `type: :program` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `:program` - - `:left` + - `namespace: String` - - `:right` + The namespace of the function to run. - - `:wheel` + - `status: :in_progress | :completed | :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` + - `class FunctionCallOutput` - - `x: Integer` + The output of a function tool call. - The x-coordinate where the click occurred. + - `call_id: String` - - `y_: Integer` + The unique ID of the function tool call generated by the model. - The y-coordinate where the click occurred. + - `output: String | BetaResponseFunctionCallOutputItemList` - - `keys: Array[String]` + Text, image, or file output of the function tool call. - The keys being held while clicking. + - `String = String` - - `class DoubleClick` + A JSON string of the output of the function tool call. - A double click action. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `keys: Array[String]` + An array of content outputs (text, image, file) for the function tool call. - The keys being held while double-clicking. + - `class BetaResponseInputTextContent` - - `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: Integer` + - `type: :input_text` - The x-coordinate where the double click occurred. + The type of the input item. Always `input_text`. - - `y_: Integer` + - `:input_text` - The y-coordinate where the double click occurred. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class Drag` + Marks the exact end of a reusable 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[Path{ 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 } - ] - ``` + - `class BetaResponseInputImageContent` - - `x: Integer` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The x-coordinate. + - `type: :input_image` - - `y_: Integer` + The type of the input item. Always `input_image`. - The y-coordinate. + - `:input_image` - - `type: :drag` + - `detail: :low | :high | :auto | :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: Array[String]` + - `:high` - The keys being held while dragging the mouse. + - `:auto` - - `class Keypress` + - `:original` - A collection of keypresses the model would like to perform. + - `file_id: String` - - `keys: Array[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: 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: PromptCacheBreakpoint{ 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. - - `class Move` + - `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`. + - `class BetaResponseInputFileContent` - - `:move` + A file input to the model. - - `x: Integer` + - `type: :input_file` - The x-coordinate to move to. + The type of the input item. Always `input_file`. - - `y_: Integer` + - `:input_file` - The y-coordinate to move to. + - `detail: :auto | :low | :high` - - `keys: Array[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` - - `class Screenshot` + - `:low` - A screenshot action. + - `:high` - - `type: :screenshot` + - `file_data: 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: String` - - `class Scroll` + The ID of the file to be sent to the model. - A scroll action. + - `file_url: String` - - `scroll_x: Integer` + The URL of the file to be sent to the model. - The horizontal scroll distance. + - `filename: String` - - `scroll_y: Integer` + The name of the file to be sent to the model. - The vertical scroll distance. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: Integer` + - `:explicit` - The x-coordinate where the scroll occurred. + - `type: :function_call_output` - - `y_: Integer` + The type of the function tool call output. Always `function_call_output`. - The y-coordinate where the scroll occurred. + - `:function_call_output` - - `keys: Array[String]` + - `id: String` - The keys being held while scrolling. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `class Type` + - `agent: Agent{ 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_: Direct{ type} | Program{ 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` + - `class Direct` - - `class Wait` + - `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`. + - `class Program` - - `:wait` + - `caller_id: String` - - `actions: 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` - - `class Click` + The caller type. Always `program`. - A click action. + - `:program` - - `class DoubleClick` + - `status: :in_progress | :completed | :incomplete` - A double click action. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `class Drag` + - `:in_progress` - A drag action. + - `:completed` - - `class Keypress` + - `:incomplete` - A collection of keypresses the model would like to perform. + - `class AgentMessage` - - `class Move` + A message routed between agents. - A mouse move action. + - `author: String` - - `class Screenshot` + The sending agent identity. - A screenshot action. + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `class Scroll` + Plaintext, image, or encrypted content sent between agents. - A scroll action. + - `class BetaResponseInputTextContent` - - `class Type` + A text input to the model. - An action to type in text. + - `class BetaResponseInputImageContent` - - `class Wait` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - A wait action. + - `class EncryptedContent` - - `agent: Agent{ 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` - - `class BetaResponseComputerToolCallOutputItem` + 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: 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: Agent{ agent_name}` - - `file_id: String` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: String` - - `image_url: String` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `class MultiAgentCall` - - `status: :completed | :incomplete | :failed | :in_progress` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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: Array[AcknowledgedSafetyCheck{ 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: String` + The item type. Always `multi_agent_call`. - The type of the pending safety check. + - `:multi_agent_call` - - `message: String` + - `id: String` - Details about the pending safety check. + The unique ID of this multi-agent call. - `agent: Agent{ agent_name}` @@ -44008,185 +53677,152 @@ Compact a response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseReasoningItem` - - 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[Summary{ text, type}]` - - Reasoning summary content. - - - `text: String` - - A summary of the reasoning output from the model so far. + - `class MultiAgentCallOutput` - - `type: :summary_text` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The type of the object. Always `summary_text`. + The multi-agent action that produced this result. - - `:summary_text` + - `:spawn_agent` - - `type: :reasoning` + - `:interrupt_agent` - The type of the object. Always `reasoning`. + - `:list_agents` - - `:reasoning` + - `:send_message` - - `agent: Agent{ agent_name}` + - `:followup_task` - The agent that produced this item. + - `:wait_agent` - - `agent_name: String` + - `call_id: String` - The canonical name of the agent that produced this item. + The unique ID of the multi-agent call. - - `content: Array[Content{ text, type}]` + - `output: Array[Output{ text, type, annotations}]` - Reasoning text content. + Text output returned by the multi-agent action. - `text: String` - The reasoning text from the model. - - - `type: :reasoning_text` + The text content. - The type of the reasoning text. Always `reasoning_text`. + - `type: :output_text` - - `:reasoning_text` + The content type. Always `output_text`. - - `encrypted_content: String` + - `:output_text` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `status: :in_progress | :completed | :incomplete` + Citations associated with the text content. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `:in_progress` + - `file_id: String` - - `:completed` + The ID of the file. - - `:incomplete` + - `filename: String` - - `class Program` + The filename of the file cited. - - `id: String` + - `index: Integer` - The unique ID of the program item. + The index of the file in the list of files. - - `call_id: String` + - `type: :file_citation` - The stable call ID of the program item. + The citation type. Always `file_citation`. - - `code: String` + - `:file_citation` - The JavaScript source executed by programmatic tool calling. + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `fingerprint: String` + - `end_index: Integer` - Opaque program replay fingerprint that must be round-tripped. + The index of the last character of the citation in the message. - - `type: :program` + - `start_index: Integer` - The type of the item. Always `program`. + The index of the first character of the citation in the message. - - `:program` + - `title: String` - - `agent: Agent{ agent_name}` + The title of the cited resource. - The agent that produced this item. + - `type: :url_citation` - - `agent_name: String` + The citation type. Always `url_citation`. - The canonical name of the agent that produced this item. + - `:url_citation` - - `class ProgramOutput` + - `url: String` - - `id: String` + The URL of the cited resource. - The unique ID of the program output item. + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `call_id: String` + - `container_id: String` - The call ID of the program item. + The ID of the container. - - `result: String` + - `end_index: Integer` - The result produced by the program item. + The index of the last character of the citation in the message. - - `status: :completed | :incomplete` + - `file_id: String` - The terminal status of the program output item. + The ID of the container file. - - `:completed` + - `filename: String` - - `:incomplete` + The filename of the container file cited. - - `type: :program_output` + - `start_index: Integer` - The type of the item. Always `program_output`. + The index of the first character of the citation in the message. - - `:program_output` + - `type: :container_file_citation` - - `agent: Agent{ agent_name}` + The citation type. Always `container_file_citation`. - The agent that produced this item. + - `:container_file_citation` - - `agent_name: String` + - `type: :multi_agent_call_output` - The canonical name of the agent that produced this item. + The item type. Always `multi_agent_call_output`. - - `class BetaResponseToolSearchCall` + - `:multi_agent_call_output` - `id: String` - The unique ID of the tool search call item. - - - `arguments: untyped` - - Arguments used for the tool search call. - - - `call_id: String` - - The unique ID of the tool search call generated by the model. - - - `execution: :server | :client` - - Whether tool search was executed by the server or by the client. + The unique ID of this multi-agent call output. - - `:server` + - `agent: Agent{ agent_name}` - - `:client` + The agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `agent_name: String` - The status of the tool search call item that was recorded. + The canonical name of the agent that produced this item. - - `:in_progress` + - `class ToolSearchCall` - - `:completed` + - `arguments: untyped` - - `: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: String` + + The unique ID of this tool search call. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -44195,16 +53831,6 @@ Compact a response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem` - - - `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. @@ -44219,7 +53845,7 @@ Compact a response - `status: :in_progress | :completed | :incomplete` - The status of the tool search output item that was recorded. + The status of the tool search call. - `:in_progress` @@ -44227,9 +53853,11 @@ Compact a response - `:incomplete` + - `class BetaResponseToolSearchOutputItemParam` + - `tools: Array[BetaTool]` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool` @@ -44328,7 +53956,7 @@ Compact a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -44338,7 +53966,11 @@ Compact a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -44385,7 +54017,7 @@ Compact a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -44395,7 +54027,11 @@ Compact a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -45319,10 +54955,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: String` + + The unique ID of this tool search output. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -45331,39 +54971,39 @@ Compact a response The canonical name of the agent that produced this item. - - `created_by: String` + - `call_id: String` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `class AdditionalTools` + - `execution: :server | :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 | :user | :assistant | 5 more` + - `:client` - The role that provided the additional tools. + - `status: :in_progress | :completed | :incomplete` - - `:unknown` + The status of the tool search output. - - `:user` + - `:in_progress` - - `:assistant` + - `:completed` - - `:system` + - `:incomplete` - - `:critic` + - `class AdditionalTools` - - `:discriminator` + - `role: :developer` - - `:developer` + The role that provided the additional tools. Only `developer` is supported. - - `:tool` + - `:developer` - `tools: Array[BetaTool]` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool` @@ -45431,10 +55071,14 @@ Compact a response - `type: :additional_tools` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `:additional_tools` + - `id: String` + + The unique ID of this additional tools item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -45443,17 +55087,82 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` + - `class BetaResponseReasoningItem` - 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](https://platform.openai.com/docs/guides/conversation-state). - `id: String` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `summary: Array[Summary{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ 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: String` - The encrypted content that was produced by compaction. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseCompactionItemParam` + + 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` @@ -45461,6 +55170,10 @@ Compact a response - `:compaction` + - `id: String` + + The ID of the compaction item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -45469,10 +55182,6 @@ Compact a response The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - `class ImageGenerationCall` An image generation request made by the model. @@ -45690,13 +55399,9 @@ Compact a response - `:incomplete` - - `class BetaResponseFunctionShellToolCall` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: String` + - `class ShellCall` - 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: Action{ commands, max_output_length, timeout_ms}` @@ -45704,60 +55409,30 @@ Compact a response - `commands: Array[String]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Integer` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Integer` - Optional timeout in milliseconds for the commands. + 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 | BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class BetaResponseContainerReference` - - Represents a container created with /v1/containers. - - - `container_id: String` - - - `type: :container_reference` - - The environment type. Always `container_reference`. - - - `:container_reference` - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -45774,6 +55449,8 @@ Compact a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -45784,35 +55461,43 @@ Compact a response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `environment: BetaLocalEnvironment | BetaContainerReference` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput` + - `class BetaLocalEnvironment` - The output of a shell tool call that was emitted. + - `class BetaContainerReference` - - `id: String` + - `status: :in_progress | :completed | :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: Integer` + - `:incomplete` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput` - - `output: Array[Output{ 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[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Timeout{ type} | Exit{ 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. - `class Timeout` @@ -45830,7 +55515,7 @@ Compact a response - `exit_code: Integer` - Exit code from the shell process. + The exit code returned by the shell process. - `type: :exit` @@ -45840,32 +55525,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: String` - - The identifier of the actor that created the item. - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -45882,6 +55557,8 @@ Compact a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -45892,19 +55569,27 @@ Compact a response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `max_output_length: Integer` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall` + - `status: :in_progress | :completed | :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` + + - `class ApplyPatchCall` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: String` @@ -45912,55 +55597,55 @@ Compact a response - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ 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. - `class CreateFile` - 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` - `class DeleteFile` - 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` - `class UpdateFile` - 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` @@ -45978,6 +55663,10 @@ Compact a response - `:apply_patch_call` + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -45994,6 +55683,8 @@ Compact a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -46004,19 +55695,13 @@ Compact a response - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `:program` - - `id: String` + - `class ApplyPatchCallOutput` - 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` @@ -46036,6 +55721,10 @@ Compact a response - `:apply_patch_call_output` + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -46052,6 +55741,8 @@ Compact a response - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -46062,15 +55753,131 @@ Compact a response - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `output: String` - The ID of the entity that created this tool call output. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `output: String` + - `class McpListTools` - Optional textual output returned by the apply patch tool. + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. - `class McpCall` @@ -46133,530 +55940,999 @@ Compact a response - `:failed` - - `class McpListTools` + - `class BetaResponseCustomToolCallOutput` - A list of tools available on an MCP server. + 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + 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: String` - The unique ID of the list. + The unique ID of the custom tool call output in the OpenAI platform. - - `server_label: String` + - `agent: Agent{ agent_name}` - The label of the MCP server. + The agent that produced this item. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `agent_name: String` - The tools available on the server. + The canonical name of the agent that produced this item. - - `input_schema: untyped` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The JSON schema describing the tool's input. + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + 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: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. + + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 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"` + + - `:"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 = String` + + - `object: :response` + + The object type of this resource - always set to `response`. + + - `:response` + + - `output: Array[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. + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall` + + 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. + + - `class BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem` + + - `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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the function call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the function call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `status: :in_progress | :completed | :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 function tool call output. Always `function_call_output`. + + - `:function_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `name: String` + The execution context that produced this tool call. - The name of the tool. + - `class Direct` - - `annotations: untyped` + - `type: :direct` - Additional annotations about the tool. + The caller type. Always `direct`. - - `description: String` + - `:direct` - The description of the tool. + - `class Program` - - `type: :mcp_list_tools` + - `caller_id: String` - The type of the item. Always `mcp_list_tools`. + The call ID of the program item that produced this tool call. - - `:mcp_list_tools` + - `type: :program` - - `agent: Agent{ agent_name}` + The caller type. Always `program`. - The agent that produced this item. + - `:program` - - `agent_name: String` + - `created_by: String` - The canonical name of the agent that produced this item. + The identifier of the actor that created the item. - - `error: String` + - `class AgentMessage` - Error message if the server could not list tools. + - `id: String` - - `class McpApprovalRequest` + The unique ID of the agent message. - A request for human approval of a tool invocation. + - `author: String` - - `id: String` + The sending agent identity. - The unique ID of the approval request. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `arguments: String` + Encrypted content sent between agents. - A JSON string of arguments for the tool. + - `class BetaResponseInputText` - - `name: String` + A text input to the model. - The name of the tool to run. + - `class BetaResponseOutputText` - - `server_label: String` + A text output from the model. - The label of the MCP server making the request. + - `class Text` - - `type: :mcp_approval_request` + A text content. - The type of the item. Always `mcp_approval_request`. + - `text: String` - - `:mcp_approval_request` + - `type: :text` - - `agent: Agent{ agent_name}` + - `:text` - The agent that produced this item. + - `class SummaryText` - - `agent_name: String` + A summary text from the model. - The canonical name of the agent that produced this item. + - `text: String` - - `class McpApprovalResponse` + A summary of the reasoning output from the model so far. - A response to an MCP approval request. + - `type: :summary_text` - - `id: String` + The type of the object. Always `summary_text`. - The unique ID of the approval response + - `:summary_text` - - `approval_request_id: String` + - `class ReasoningText` - The ID of the approval request being answered. + Reasoning text from the model. - - `approve: bool` + - `text: String` - Whether the request was approved. + The reasoning text from the model. - - `type: :mcp_approval_response` + - `type: :reasoning_text` - The type of the item. Always `mcp_approval_response`. + The type of the reasoning text. Always `reasoning_text`. - - `:mcp_approval_response` + - `:reasoning_text` - - `agent: Agent{ agent_name}` + - `class BetaResponseOutputRefusal` - The agent that produced this item. + A refusal from the model. - - `agent_name: String` + - `class BetaResponseInputImage` - 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). - - `reason: String` + - `class ComputerScreenshot` - Optional reason for the decision. + A screenshot of a computer. - - `class BetaResponseCustomToolCall` + - `detail: :low | :high | :auto | :original` - A call to a custom tool created by the model. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `call_id: String` + - `:low` - An identifier used to map this custom tool call to a tool call output. + - `:high` - - `input: String` + - `:auto` - The input for the custom tool call generated by the model. + - `:original` - - `name: String` + - `file_id: String` - The name of the custom tool being called. + The identifier of an uploaded file that contains the screenshot. - - `type: :custom_tool_call` + - `image_url: String` - The type of the custom tool call. Always `custom_tool_call`. + The URL of the screenshot image. - - `:custom_tool_call` + - `type: :computer_screenshot` - - `id: String` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The unique ID of the custom tool call in the OpenAI platform. + - `:computer_screenshot` - - `agent: Agent{ agent_name}` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `agent_name: String` + - `mode: :explicit` - The canonical name of the agent that produced this item. + The breakpoint mode. Always `explicit`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:explicit` - The execution context that produced this tool call. + - `class BetaResponseInputFile` - - `class Direct` + A file input to the model. - - `type: :direct` + - `class EncryptedContent` - - `:direct` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `class Program` + - `encrypted_content: String` - - `caller_id: String` + Opaque encrypted content. - The call ID of the program item that produced this tool call. + - `type: :encrypted_content` - - `type: :program` + The type of the input item. Always `encrypted_content`. - - `:program` + - `:encrypted_content` - - `namespace: String` + - `recipient: String` - The namespace of the custom tool being called. + The destination agent identity. - - `class BetaResponseCustomToolCallOutputItem` + - `type: :agent_message` - The output of a custom tool call from your code, being sent back to the model. + The type of the item. Always `agent_message`. - - `id: String` + - `:agent_message` - The unique ID of the custom tool call output item. + - `agent: Agent{ agent_name}` - - `status: :in_progress | :completed | :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` + - `class MultiAgentCall` - - `:incomplete` + - `id: String` - - `created_by: String` + The unique ID of the multi-agent call item. - The identifier of the actor that created the item. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `usage: BetaResponseUsage` + The multi-agent action to execute. - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + - `:spawn_agent` - - `input_tokens: Integer` + - `:interrupt_agent` - The number of input tokens. + - `:list_agents` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `:send_message` - A detailed breakdown of the input tokens. + - `:followup_task` - - `cache_write_tokens: Integer` + - `:wait_agent` - The number of input tokens that were written to the cache. + - `arguments: String` - - `cached_tokens: Integer` + The JSON string of arguments generated for the action. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `call_id: String` - - `output_tokens: Integer` + The unique ID linking this call to its output. - The number of output tokens. + - `type: :multi_agent_call` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + The type of the multi-agent call. Always `multi_agent_call`. - A detailed breakdown of the output tokens. + - `:multi_agent_call` - - `reasoning_tokens: Integer` + - `agent: Agent{ agent_name}` - The number of reasoning tokens. + The agent that produced this item. - - `total_tokens: Integer` + - `agent_name: String` - The total number of tokens used. + The canonical name of the agent that produced this item. -### Example + - `class MultiAgentCallOutput` -```ruby -require "openai" + - `id: String` -openai = OpenAI::Client.new(api_key: "My API Key") + The unique ID of the multi-agent call output item. -beta_compacted_response = openai.beta.responses.compact(model: :"gpt-5.6-sol") + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` -puts(beta_compacted_response) -``` + The multi-agent action that produced this result. -#### Response + - `:spawn_agent` -```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 - } -} -``` + - `:interrupt_agent` -## Domain Types + - `:list_agents` -### Beta Apply Patch Tool + - `:send_message` -- `class BetaApplyPatchTool` + - `:followup_task` - Allows the assistant to create, delete, or update files using unified diffs. + - `:wait_agent` - - `type: :apply_patch` + - `call_id: String` - The type of the tool. Always `apply_patch`. + The unique ID of the multi-agent call. - - `:apply_patch` + - `output: Array[BetaResponseOutputText]` - - `allowed_callers: Array[:direct | :programmatic]` + Text output returned by the multi-agent action. - The tool invocation context(s). + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:direct` + The annotations of the text output. - - `:programmatic` + - `text: String` -### Beta Compacted Response + The text output from the model. -- `class BetaCompactedResponse` + - `type: :output_text` - - `id: String` + The type of the output text. Always `output_text`. - The unique identifier for the compacted response. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `created_at: Integer` + - `type: :multi_agent_call_output` - Unix timestamp (in seconds) when the compacted conversation was created. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `object: :"response.compaction"` + - `:multi_agent_call_output` - The object type. Always `response.compaction`. + - `agent: Agent{ agent_name}` - - `:"response.compaction"` + The agent that produced this item. - - `output: Array[BetaResponseOutputItem]` + - `agent_name: String` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + The canonical name of the agent that produced this item. - - `class BetaResponseOutputMessage` + - `class BetaResponseFunctionWebSearch` - An output message from the model. + 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` + - `class BetaResponseComputerToolCall` - The unique ID of the output message. + 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. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `class BetaResponseComputerToolCallOutputItem` - The content of the output message. + - `id: String` - - `class BetaResponseOutputText` + The unique ID of the computer call tool output. - A text output from the model. + - `call_id: String` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The ID of the computer tool call that produced the output. - The annotations of the text output. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `class FileCitation` + A computer screenshot image used with the computer use tool. - A citation to a file. + - `status: :completed | :incomplete | :failed | :in_progress` - - `file_id: String` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The ID of the file. + - `:completed` - - `filename: String` + - `:incomplete` - The filename of the file cited. + - `:failed` - - `index: Integer` + - `:in_progress` - The index of the file in the list of files. + - `type: :computer_call_output` - - `type: :file_citation` + The type of the computer tool call output. Always `computer_call_output`. - The type of the file citation. Always `file_citation`. + - `:computer_call_output` - - `:file_citation` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `class URLCitation` + The safety checks reported by the API that have been acknowledged by the + developer. - A citation for a web resource used to generate a model response. + - `id: String` - - `end_index: Integer` + The ID of the pending safety check. - The index of the last character of the URL citation in the message. + - `code: String` - - `start_index: Integer` + The type of the pending safety check. - The index of the first character of the URL citation in the message. + - `message: String` - - `title: String` + Details about the pending safety check. - The title of the web resource. + - `agent: Agent{ agent_name}` - - `type: :url_citation` + The agent that produced this item. - The type of the URL citation. Always `url_citation`. + - `agent_name: String` - - `:url_citation` + The canonical name of the agent that produced this item. - - `url: String` + - `created_by: String` - The URL of the web resource. + The identifier of the actor that created the item. - - `class ContainerFileCitation` + - `class BetaResponseReasoningItem` - A citation for a container file used to generate 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). - - `container_id: String` + - `class Program` - The ID of the container file. + - `id: String` - - `end_index: Integer` + The unique ID of the program item. - The index of the last character of the container file citation in the message. + - `call_id: String` - - `file_id: String` + The stable call ID of the program item. - The ID of the file. + - `code: String` - - `filename: String` + The JavaScript source executed by programmatic tool calling. - The filename of the container file cited. + - `fingerprint: String` - - `start_index: Integer` + Opaque program replay fingerprint that must be round-tripped. - The index of the first character of the container file citation in the message. + - `type: :program` - - `type: :container_file_citation` + The type of the item. Always `program`. - The type of the container file citation. Always `container_file_citation`. + - `:program` - - `:container_file_citation` + - `agent: Agent{ agent_name}` - - `class FilePath` + 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. + - `class ProgramOutput` - - `index: Integer` + - `id: String` - The index of the file in the list of files. + The unique ID of the program output item. - - `type: :file_path` + - `call_id: String` - The type of the file path. Always `file_path`. + The call ID of the program item. - - `:file_path` + - `result: String` - - `text: String` + The result produced by the program item. - The text output from the model. + - `status: :completed | :incomplete` - - `type: :output_text` + The terminal status of the program output item. - The type of the output text. Always `output_text`. + - `:completed` - - `:output_text` + - `:incomplete` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `type: :program_output` - - `token: String` + The type of the item. Always `program_output`. - - `bytes: Array[Integer]` + - `:program_output` - - `logprob: Float` + - `agent: Agent{ agent_name}` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + The agent that produced this item. - - `token: String` + - `agent_name: String` - - `bytes: Array[Integer]` + The canonical name of the agent that produced this item. - - `logprob: Float` + - `class BetaResponseToolSearchCall` - - `class BetaResponseOutputRefusal` + - `id: String` - A refusal from the model. + The unique ID of the tool search call item. - - `refusal: String` + - `arguments: untyped` - The refusal explanation from the model. + Arguments used for the tool search call. - - `type: :refusal` + - `call_id: String` - The type of the refusal. Always `refusal`. + The unique ID of the tool search call generated by the model. - - `:refusal` + - `execution: :server | :client` - - `role: :assistant` + Whether tool search was executed by the server or by the client. - The role of the output message. Always `assistant`. + - `:server` - - `:assistant` + - `:client` - `status: :in_progress | :completed | :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 tool search call item that was recorded. - `:in_progress` @@ -46664,11 +56940,11 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :message` + - `type: :tool_search_call` - The type of the output message. Always `message`. + The type of the item. Always `tool_search_call`. - - `:message` + - `:tool_search_call` - `agent: Agent{ agent_name}` @@ -46678,116 +56954,111 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `created_by: String` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The identifier of the actor that created the item. - - `:commentary` + - `class BetaResponseToolSearchOutputItem` - - `class BetaResponseFileSearchToolCall` + - `id: String` - 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 unique ID of the tool search output item. - - `id: String` + - `call_id: String` - The unique ID of the file search tool call. + The unique ID of the tool search call generated by the model. - - `queries: Array[String]` + - `execution: :server | :client` - The queries used to search for files. + Whether tool search was executed by the server or by the client. - - `status: :in_progress | :searching | :completed | 2 more` + - `:server` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `:client` - - `:in_progress` + - `status: :in_progress | :completed | :incomplete` - - `:searching` + The status of the tool search output item that was recorded. + + - `:in_progress` - `:completed` - `:incomplete` - - `:failed` + - `tools: Array[BetaTool]` - - `type: :file_search_call` + The loaded tool definitions returned by tool search. - The type of the file search tool call. Always `file_search_call`. + - `class BetaFunctionTool` - - `:file_search_call` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `agent: Agent{ agent_name}` + - `class BetaFileSearchTool` - 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` + - `class BetaComputerTool` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `class BetaComputerUsePreviewTool` - The results of the file search tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `attributes: Hash[Symbol, String | Float | bool]` + - `class BetaWebSearchTool` - Set of 16 key-value pairs that can be attached to an object. 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. + 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). - - `String = String` + - `class Mcp` - - `Float = Float` + 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). - - `UnionMember2 = bool` + - `class CodeInterpreter` - - `file_id: String` + A tool that runs Python code to help generate a response to a prompt. - The unique ID of the file. + - `class ProgrammaticToolCalling` - - `filename: String` + - `class ImageGeneration` - The name of the file. + A tool that generates images using the GPT image models. - - `score: Float` + - `class LocalShell` - The relevance score of the file - a value between 0 and 1. + A tool that allows the model to execute shell commands in a local environment. - - `text: String` + - `class BetaFunctionShellTool` - The text that was retrieved from the file. + A tool that allows the model to execute shell commands. - - `class BetaResponseFunctionToolCall` + - `class BetaCustomTool` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) 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) - - `arguments: String` + - `class BetaNamespaceTool` - A JSON string of the arguments to pass to the function. + Groups function/custom tools under a shared namespace. - - `call_id: String` + - `class BetaToolSearchTool` - The unique ID of the function tool call generated by the model. + Hosted or BYOT tool search configuration for deferred tools. - - `name: String` + - `class BetaWebSearchPreviewTool` - The name of the function to run. + 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: :function_call` + - `class BetaApplyPatchTool` - The type of the function tool call. Always `function_call`. + Allows the assistant to create, delete, or update files using unified diffs. - - `:function_call` + - `type: :tool_search_output` - - `id: String` + The type of the item. Always `tool_search_output`. - The unique ID of the function tool call. + - `:tool_search_output` - `agent: Agent{ agent_name}` @@ -46797,190 +57068,177 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. + - `created_by: String` - - `type: :program` + The identifier of the actor that created the item. - - `:program` + - `class AdditionalTools` - - `namespace: String` + - `id: String` - The namespace of the function to run. + The unique ID of the additional tools item. - - `status: :in_progress | :completed | :incomplete` + - `role: :unknown | :user | :assistant | 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` - - `class BetaResponseFunctionToolCallOutputItem` + - `:system` - - `id: String` + - `:critic` - The unique ID of the function call tool output. + - `:discriminator` - - `call_id: String` + - `:developer` - The unique ID of the function tool call generated by the model. + - `:tool` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `tools: Array[BetaTool]` - The output from the function call generated by your code. - Can be a string or an list of output content. + The additional tool definitions made available at this item. - - `String = String` + - `class BetaFunctionTool` - A string of the output of the 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). - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class BetaFileSearchTool` - Text, image, or file output of the function 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). - - `class BetaResponseInputText` + - `class BetaComputerTool` - A text input to the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `text: String` + - `class BetaComputerUsePreviewTool` - The text input to the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :input_text` + - `class BetaWebSearchTool` - The type of the input item. Always `input_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). - - `:input_text` + - `class Mcp` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + 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). - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class CodeInterpreter` - - `mode: :explicit` + A tool that runs Python code to help generate a response to a prompt. - The breakpoint mode. Always `explicit`. + - `class ProgrammaticToolCalling` - - `:explicit` + - `class ImageGeneration` - - `class BetaResponseInputImage` + A tool that generates images using the GPT image models. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class LocalShell` - - `detail: :low | :high | :auto | :original` + A tool that allows the model to execute shell commands in a local environment. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class BetaFunctionShellTool` - - `:low` + A tool that allows the model to execute shell commands. - - `:high` + - `class BetaCustomTool` - - `: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) - - `:original` + - `class BetaNamespaceTool` - - `type: :input_image` + Groups function/custom tools under a shared namespace. - The type of the input item. Always `input_image`. + - `class BetaToolSearchTool` - - `:input_image` + Hosted or BYOT tool search configuration for deferred tools. - - `file_id: String` + - `class BetaWebSearchPreviewTool` - The ID of the file to be sent to the model. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `image_url: String` + - `class BetaApplyPatchTool` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Allows the assistant to create, delete, or update files using unified diffs. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `type: :additional_tools` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the item. Always `additional_tools`. - - `mode: :explicit` + - `:additional_tools` - The breakpoint mode. Always `explicit`. + - `agent: Agent{ agent_name}` - - `:explicit` + The agent that produced this item. - - `class BetaResponseInputFile` + - `agent_name: String` - A file input to the model. + The canonical name of the agent that produced this item. - - `type: :input_file` + - `class BetaResponseCompactionItem` - The type of the input item. Always `input_file`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:input_file` + - `id: String` - - `detail: :auto | :low | :high` + The unique ID of the compaction 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`. + - `encrypted_content: String` - - `:auto` + The encrypted content that was produced by compaction. - - `:low` + - `type: :compaction` - - `:high` + The type of the item. Always `compaction`. - - `file_data: String` + - `:compaction` - The content of the file to be sent to the model. + - `agent: Agent{ agent_name}` - - `file_id: String` + The agent that produced this item. - The ID of the file to be sent to the model. + - `agent_name: String` - - `file_url: String` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. + - `created_by: String` - - `filename: String` + The identifier of the actor that created the item. - The name of the file to be sent to the model. + - `class ImageGenerationCall` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + An image generation request made 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. + - `id: String` - - `mode: :explicit` + The unique ID of the image generation call. - The breakpoint mode. Always `explicit`. + - `result: String` - - `:explicit` + The generated image encoded in base64. - - `status: :in_progress | :completed | :incomplete` + - `status: :in_progress | :completed | :generating | :failed` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the image generation call. - `:in_progress` - `:completed` - - `:incomplete` + - `:generating` - - `type: :function_call_output` + - `:failed` - The type of the function tool call output. Always `function_call_output`. + - `type: :image_generation_call` - - `:function_call_output` + The type of the image generation call. Always `image_generation_call`. + + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -46990,169 +57248,179 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseCodeInterpreterToolCall` - The execution context that produced this tool call. + A tool call to run code. - - `class Direct` + - `class LocalShellCall` - - `type: :direct` + A tool call to run a command on the local shell. - The caller type. Always `direct`. + - `id: String` - - `:direct` + The unique ID of the local shell call. - - `class Program` + - `action: Action{ command, env, type, 3 more}` - - `caller_id: String` + Execute a shell command on the server. - The call ID of the program item that produced this tool call. + - `command: Array[String]` - - `type: :program` + The command to run. - The caller type. Always `program`. + - `env: Hash[Symbol, String]` - - `:program` + Environment variables to set for the command. - - `created_by: String` + - `type: :exec` - The identifier of the actor that created the item. + The type of the local shell action. Always `exec`. - - `class AgentMessage` + - `:exec` - - `id: String` + - `timeout_ms: Integer` - The unique ID of the agent message. + Optional timeout in milliseconds for the command. - - `author: String` + - `user: String` - The sending agent identity. + Optional user to run the command as. - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `working_directory: String` - Encrypted content sent between agents. + Optional working directory to run the command in. - - `class BetaResponseInputText` + - `call_id: String` - A text input to the model. + The unique ID of the local shell tool call generated by the model. - - `class BetaResponseOutputText` + - `status: :in_progress | :completed | :incomplete` - A text output from the model. + The status of the local shell call. - - `class Text` + - `:in_progress` - A text content. + - `:completed` - - `text: String` + - `:incomplete` - - `type: :text` + - `type: :local_shell_call` - - `:text` + The type of the local shell call. Always `local_shell_call`. - - `class SummaryText` + - `:local_shell_call` - A summary text from the model. + - `agent: Agent{ agent_name}` - - `text: String` + The agent that produced this item. - A summary of the reasoning output from the model so far. + - `agent_name: String` - - `type: :summary_text` + The canonical name of the agent that produced this item. - The type of the object. Always `summary_text`. + - `class LocalShellCallOutput` - - `:summary_text` + The output of a local shell tool call. - - `class ReasoningText` + - `id: String` - Reasoning text from the model. + The unique ID of the local shell tool call generated by the model. - - `text: String` + - `output: String` - The reasoning text from the model. + A JSON string of the output of the local shell tool call. - - `type: :reasoning_text` + - `type: :local_shell_call_output` - The type of the reasoning text. Always `reasoning_text`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:reasoning_text` + - `:local_shell_call_output` - - `class BetaResponseOutputRefusal` + - `agent: Agent{ agent_name}` - A refusal from the model. + The agent that produced this item. - - `class BetaResponseInputImage` + - `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. - - `class ComputerScreenshot` + - `status: :in_progress | :completed | :incomplete` - A screenshot of a computer. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `detail: :low | :high | :auto | :original` + - `:in_progress` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:completed` - - `:low` + - `:incomplete` - - `:high` + - `class BetaResponseFunctionShellToolCall` - - `:auto` + A tool call that executes one or more shell commands in a managed environment. - - `:original` + - `id: String` - - `file_id: String` + The unique ID of the shell tool call. Populated when this item is returned via API. - The identifier of an uploaded file that contains the screenshot. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `image_url: String` + The shell commands and limits that describe how to run the tool call. - The URL of the screenshot image. + - `commands: Array[String]` - - `type: :computer_screenshot` + - `max_output_length: Integer` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Optional maximum number of characters to return from each command. - - `:computer_screenshot` + - `timeout_ms: Integer` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Optional timeout in milliseconds for the 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. + - `call_id: String` - - `mode: :explicit` + The unique ID of the shell tool call generated by the model. - The breakpoint mode. Always `explicit`. + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:explicit` + Represents the use of a local environment to perform shell actions. - - `class BetaResponseInputFile` + - `class BetaResponseLocalEnvironment` - A file input to the model. + Represents the use of a local environment to perform shell actions. - - `class EncryptedContent` + - `type: :local` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The environment type. Always `local`. - - `encrypted_content: String` + - `:local` - Opaque encrypted content. + - `class BetaResponseContainerReference` - - `type: :encrypted_content` + Represents a container created with /v1/containers. - The type of the input item. Always `encrypted_content`. + - `container_id: String` - - `:encrypted_content` + - `type: :container_reference` - - `recipient: String` + The environment type. Always `container_reference`. - The destination agent identity. + - `:container_reference` - - `type: :agent_message` + - `status: :in_progress | :completed | :incomplete` - The type of the item. Always `agent_message`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:agent_message` + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :shell_call` + + The type of the item. Always `shell_call`. + + - `:shell_call` - `agent: Agent{ agent_name}` @@ -47162,99 +57430,105 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCall` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the multi-agent call item. + - `class Direct` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :direct` - The multi-agent action to execute. + - `:direct` - - `:spawn_agent` + - `class Program` - - `:interrupt_agent` + - `caller_id: String` - - `:list_agents` + The call ID of the program item that produced this tool call. - - `:send_message` + - `type: :program` - - `:followup_task` + - `:program` - - `:wait_agent` + - `created_by: String` - - `arguments: String` + The ID of the entity that created this tool call. - The JSON string of arguments generated for the action. + - `class BetaResponseFunctionShellToolCallOutput` + + 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 linking this call to its output. + The unique ID of the shell tool call generated by the model. - - `type: :multi_agent_call` + - `max_output_length: Integer` - The type of the multi-agent call. Always `multi_agent_call`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `:multi_agent_call` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `agent: Agent{ agent_name}` + An array of shell call output contents - The agent that produced this item. + - `outcome: Timeout{ type} | Exit{ 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. + - `class Timeout` - - `class MultiAgentCallOutput` + Indicates that the shell call exceeded its configured time limit. - - `id: String` + - `type: :timeout` - The unique ID of the multi-agent call output item. + The outcome type. Always `timeout`. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:timeout` - The multi-agent action that produced this result. + - `class Exit` - - `:spawn_agent` + Indicates that the shell commands finished and returned an exit code. - - `:interrupt_agent` + - `exit_code: Integer` - - `:list_agents` + Exit code from the shell process. - - `:send_message` + - `type: :exit` - - `:followup_task` + The outcome type. Always `exit`. - - `:wait_agent` + - `:exit` - - `call_id: String` + - `stderr: String` - The unique ID of the multi-agent call. + The standard error output that was captured. - - `output: Array[BetaResponseOutputText]` + - `stdout: String` - Text output returned by the multi-agent action. + The standard output that was captured. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `created_by: String` - The annotations of the text output. + The identifier of the actor that created the item. - - `text: String` + - `status: :in_progress | :completed | :incomplete` - The text output from the model. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `type: :output_text` + - `:in_progress` - The type of the output text. Always `output_text`. + - `:completed` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:incomplete` - - `type: :multi_agent_call_output` + - `type: :shell_call_output` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the shell call output. Always `shell_call_output`. - - `:multi_agent_call_output` + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -47264,1899 +57538,1936 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch` - - 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. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the web search tool call. + - `class Direct` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `type: :direct` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `:direct` - - `class Search` + - `class Program` - Action type "search" - Performs a web search query. + - `caller_id: String` - - `type: :search` + The call ID of the program item that produced this tool call. - The action type. + - `type: :program` - - `:search` + - `:program` - - `queries: Array[String]` + - `created_by: String` - The search queries. + The identifier of the actor that created the item. - - `query: String` + - `class BetaResponseApplyPatchToolCall` - The search query. + A tool call that applies file diffs by creating, deleting, or updating files. - - `sources: Array[Source{ type, url}]` + - `id: String` - The sources used in the search. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `type: :url` + - `call_id: String` - The type of source. Always `url`. + The unique ID of the apply patch tool call generated by the model. - - `:url` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `url: String` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The URL of the source. + - `class CreateFile` - - `class OpenPage` + Instruction describing how to create a file via the apply_patch tool. - Action type "open_page" - Opens a specific URL from search results. + - `diff: String` - - `type: :open_page` + Diff to apply. - The action type. + - `path: String` - - `:open_page` + Path of the file to create. - - `url: String` + - `type: :create_file` - The URL opened by the model. + Create a new file with the provided diff. - - `class FindInPage` + - `:create_file` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `class DeleteFile` - - `pattern: String` + Instruction describing how to delete a file via the apply_patch tool. - The pattern or text to search for within the page. + - `path: String` - - `type: :find_in_page` + Path of the file to delete. - The action type. + - `type: :delete_file` - - `:find_in_page` + Delete the specified file. - - `url: String` + - `:delete_file` - The URL of the page searched for the pattern. + - `class UpdateFile` - - `status: :in_progress | :searching | :completed | :failed` + Instruction describing how to update a file via the apply_patch tool. - The status of the web search tool call. + - `diff: String` - - `:in_progress` + Diff to apply. - - `:searching` + - `path: String` - - `:completed` + Path of the file to update. - - `:failed` + - `type: :update_file` - - `type: :web_search_call` + Update an existing file with the provided diff. - The type of the web search tool call. Always `web_search_call`. + - `:update_file` - - `:web_search_call` + - `status: :in_progress | :completed` - - `agent: Agent{ agent_name}` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The agent that produced this item. + - `:in_progress` - - `agent_name: String` + - `:completed` - The canonical name of the agent that produced this item. + - `type: :apply_patch_call` - - `class BetaResponseComputerToolCall` + The type of the item. Always `apply_patch_call`. - 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. + - `:apply_patch_call` - - `id: String` + - `agent: Agent{ agent_name}` - The unique ID of the computer call. + The agent that produced this item. - - `call_id: String` + - `agent_name: String` - An identifier used when responding to the tool call with output. + The canonical name of the agent that produced this item. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The pending safety checks for the computer call. + The execution context that produced this tool call. - - `id: String` + - `class Direct` - The ID of the pending safety check. + - `type: :direct` - - `code: String` + - `:direct` - The type of the pending safety check. + - `class Program` - - `message: String` + - `caller_id: String` - Details about the pending safety check. + The call ID of the program item that produced this tool call. - - `status: :in_progress | :completed | :incomplete` + - `type: :program` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:program` - - `:in_progress` + - `created_by: String` - - `:completed` + The ID of the entity that created this tool call. - - `:incomplete` + - `class BetaResponseApplyPatchToolCallOutput` - - `type: :computer_call` + The output emitted by an apply patch tool call. - The type of the computer call. Always `computer_call`. + - `id: String` - - `:computer_call` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `action: BetaComputerAction` + - `call_id: String` - A click action. + The unique ID of the apply patch tool call generated by the model. - - `class Click` + - `status: :completed | :failed` - A click action. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `button: :left | :right | :wheel | 2 more` + - `:completed` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `:failed` - - `:left` + - `type: :apply_patch_call_output` - - `:right` + The type of the item. Always `apply_patch_call_output`. - - `:wheel` + - `:apply_patch_call_output` - - `:back` + - `agent: Agent{ agent_name}` - - `:forward` + The agent that produced this item. - - `type: :click` + - `agent_name: String` - Specifies the event type. For a click action, this property is always `click`. + The canonical name of the agent that produced this item. - - `:click` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `x: Integer` + The execution context that produced this tool call. - The x-coordinate where the click occurred. + - `class Direct` - - `y_: Integer` + - `type: :direct` - The y-coordinate where the click occurred. + - `:direct` - - `keys: Array[String]` + - `class Program` - The keys being held while clicking. + - `caller_id: String` - - `class DoubleClick` + The call ID of the program item that produced this tool call. - A double click action. + - `type: :program` - - `keys: Array[String]` + - `:program` - The keys being held while double-clicking. + - `created_by: String` - - `type: :double_click` + The ID of the entity that created this tool call output. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `output: String` - - `:double_click` + Optional textual output returned by the apply patch tool. - - `x: Integer` + - `class McpCall` - The x-coordinate where the double click occurred. + An invocation of a tool on an MCP server. - - `y_: Integer` + - `id: String` - The y-coordinate where the double click occurred. + The unique ID of the tool call. - - `class Drag` + - `arguments: String` - A drag action. + A JSON string of the arguments passed to the tool. - - `path: Array[Path{ x, y_}]` + - `name: String` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The name of the tool that was run. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `server_label: String` - - `x: Integer` + The label of the MCP server running the tool. - The x-coordinate. + - `type: :mcp_call` - - `y_: Integer` + The type of the item. Always `mcp_call`. - The y-coordinate. + - `:mcp_call` - - `type: :drag` + - `agent: Agent{ agent_name}` - Specifies the event type. For a drag action, this property is always set to `drag`. + The agent that produced this item. - - `:drag` + - `agent_name: String` - - `keys: Array[String]` + The canonical name of the agent that produced this item. - The keys being held while dragging the mouse. + - `approval_request_id: String` - - `class Keypress` + 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 collection of keypresses the model would like to perform. + - `error: String` - - `keys: Array[String]` + The error from the tool call, if any. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `output: String` - - `type: :keypress` + The output from the tool call. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `:keypress` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `class Move` + - `:in_progress` - A mouse move action. + - `:completed` - - `type: :move` + - `:incomplete` - Specifies the event type. For a move action, this property is always set to `move`. + - `:calling` - - `:move` + - `:failed` - - `x: Integer` + - `class McpListTools` - The x-coordinate to move to. + A list of tools available on an MCP server. - - `y_: Integer` + - `id: String` - The y-coordinate to move to. + The unique ID of the list. - - `keys: Array[String]` + - `server_label: String` - The keys being held while moving the mouse. + The label of the MCP server. - - `class Screenshot` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - A screenshot action. + The tools available on the server. - - `type: :screenshot` + - `input_schema: untyped` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The JSON schema describing the tool's input. - - `:screenshot` + - `name: String` - - `class Scroll` + The name of the tool. - A scroll action. + - `annotations: untyped` - - `scroll_x: Integer` + Additional annotations about the tool. - The horizontal scroll distance. + - `description: String` - - `scroll_y: Integer` + The description of the tool. - The vertical scroll distance. + - `type: :mcp_list_tools` - - `type: :scroll` + The type of the item. Always `mcp_list_tools`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `:mcp_list_tools` - - `:scroll` + - `agent: Agent{ agent_name}` - - `x: Integer` + The agent that produced this item. - The x-coordinate where the scroll occurred. + - `agent_name: String` - - `y_: Integer` + The canonical name of the agent that produced this item. - The y-coordinate where the scroll occurred. + - `error: String` - - `keys: Array[String]` + Error message if the server could not list tools. - The keys being held while scrolling. + - `class McpApprovalRequest` - - `class Type` + A request for human approval of a tool invocation. - An action to type in text. + - `id: String` - - `text: String` + The unique ID of the approval request. - The text to type. + - `arguments: String` - - `type: :type` + A JSON string of arguments for the tool. - Specifies the event type. For a type action, this property is always set to `type`. + - `name: String` - - `:type` + The name of the tool to run. - - `class Wait` + - `server_label: String` - A wait action. + The label of the MCP server making the request. - - `type: :wait` + - `type: :mcp_approval_request` - Specifies the event type. For a wait action, this property is always set to `wait`. + The type of the item. Always `mcp_approval_request`. - - `:wait` + - `:mcp_approval_request` - - `actions: BetaComputerActionList` + - `agent: Agent{ agent_name}` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The agent that produced this item. - - `class Click` + - `agent_name: String` - A click action. + The canonical name of the agent that produced this item. - - `class DoubleClick` + - `class McpApprovalResponse` - A double click action. + A response to an MCP approval request. - - `class Drag` + - `id: String` - A drag action. + The unique ID of the approval response - - `class Keypress` + - `approval_request_id: String` - A collection of keypresses the model would like to perform. + The ID of the approval request being answered. - - `class Move` + - `approve: bool` - A mouse move action. + Whether the request was approved. - - `class Screenshot` + - `type: :mcp_approval_response` - A screenshot action. + The type of the item. Always `mcp_approval_response`. - - `class Scroll` + - `:mcp_approval_response` - A scroll action. + - `agent: Agent{ agent_name}` - - `class Type` + The agent that produced this item. - An action to type in text. + - `agent_name: String` - - `class Wait` + The canonical name of the agent that produced this item. - A wait action. + - `reason: String` - - `agent: Agent{ agent_name}` + Optional reason for the decision. - The agent that produced this item. + - `class BetaResponseCustomToolCall` - - `agent_name: String` + A call to a custom tool created by the model. - The canonical name of the agent that produced this item. + - `class BetaResponseCustomToolCallOutputItem` - - `class BetaResponseComputerToolCallOutputItem` + The output of a custom tool call from your code, being sent back to the model. - `id: String` - The unique ID of the computer call tool output. - - - `call_id: String` + The unique ID of the custom tool call output item. - The ID of the computer tool call that produced the output. + - `status: :in_progress | :completed | :incomplete` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A computer screenshot image used with the computer use tool. + - `:in_progress` - - `type: :computer_screenshot` + - `:completed` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `:incomplete` - - `:computer_screenshot` + - `created_by: String` - - `file_id: String` + The identifier of the actor that created the item. - The identifier of an uploaded file that contains the screenshot. + - `parallel_tool_calls: bool` - - `image_url: String` + Whether to allow the model to run tool calls in parallel. - The URL of the screenshot image. + - `temperature: Float` - - `status: :completed | :incomplete | :failed | :in_progress` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `:completed` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `:incomplete` + - `BetaToolChoiceOptions = :none | :auto | :required` - - `:failed` + 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. - - `type: :computer_call_output` + `auto` means the model can pick between generating a message or calling one or + more tools. - The type of the computer tool call output. Always `computer_call_output`. + `required` means the model must call one or more tools. - - `:computer_call_output` + - `:none` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `:auto` - The safety checks reported by the API that have been acknowledged by the - developer. + - `:required` - - `id: String` + - `class BetaToolChoiceAllowed` - The ID of the pending safety check. + Constrains the tools available to the model to a pre-defined set. - - `code: String` + - `mode: :auto | :required` - The type of the pending safety check. + Constrains the tools available to the model to a pre-defined set. - - `message: String` + `auto` allows the model to pick from among the allowed tools and generate a + message. - Details about the pending safety check. + `required` requires the model to call one or more of the allowed tools. - - `agent: Agent{ agent_name}` + - `:auto` - The agent that produced this item. + - `:required` - - `agent_name: String` + - `tools: Array[Hash[Symbol, untyped]]` - The canonical name of the agent that produced this item. + A list of tool definitions that the model should be allowed to call. - - `created_by: String` + For the Responses API, the list of tool definitions might look like: - The identifier of the actor that created the item. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `class BetaResponseReasoningItem` + - `type: :allowed_tools` - 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). + Allowed tool configuration type. Always `allowed_tools`. - - `id: String` + - `:allowed_tools` - The unique identifier of the reasoning content. + - `class BetaToolChoiceTypes` - - `summary: Array[Summary{ text, 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). - Reasoning summary content. + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `text: String` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - A summary of the reasoning output from the model so far. + Allowed values are: - - `type: :summary_text` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The type of the object. Always `summary_text`. + - `:file_search` - - `:summary_text` + - `:web_search_preview` - - `type: :reasoning` + - `:computer` - The type of the object. Always `reasoning`. + - `:computer_use_preview` - - `:reasoning` + - `:computer_use` - - `agent: Agent{ agent_name}` + - `:web_search_preview_2025_03_11` - The agent that produced this item. + - `:image_generation` - - `agent_name: String` + - `:code_interpreter` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceFunction` - - `content: Array[Content{ text, type}]` + Use this option to force the model to call a specific function. - Reasoning text content. + - `name: String` - - `text: String` + The name of the function to call. - The reasoning text from the model. + - `type: :function` - - `type: :reasoning_text` + For function calling, the type is always `function`. - The type of the reasoning text. Always `reasoning_text`. + - `:function` - - `:reasoning_text` + - `class BetaToolChoiceMcp` - - `encrypted_content: String` + Use this option to force the model to call a specific tool on a remote MCP server. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `server_label: String` - - `status: :in_progress | :completed | :incomplete` + The label of the MCP server to use. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: :mcp` - - `:in_progress` + For MCP tools, the type is always `mcp`. - - `:completed` + - `:mcp` - - `:incomplete` + - `name: String` - - `class Program` + The name of the tool to call on the server. - - `id: String` + - `class BetaToolChoiceCustom` - The unique ID of the program item. + Use this option to force the model to call a specific custom tool. - - `call_id: String` + - `name: String` - The stable call ID of the program item. + The name of the custom tool to call. - - `code: String` + - `type: :custom` - The JavaScript source executed by programmatic tool calling. + For custom tool calling, the type is always `custom`. - - `fingerprint: String` + - `:custom` - Opaque program replay fingerprint that must be round-tripped. + - `class BetaSpecificProgrammaticToolCallingParam` - - `type: :program` + - `type: :programmatic_tool_calling` - The type of the item. Always `program`. + The tool to call. Always `programmatic_tool_calling`. - - `:program` + - `:programmatic_tool_calling` - - `agent: Agent{ agent_name}` + - `class BetaToolChoiceApplyPatch` - The agent that produced this item. + Forces the model to call the apply_patch tool when executing a tool call. - - `agent_name: String` + - `type: :apply_patch` - The canonical name of the agent that produced this item. + The tool to call. Always `apply_patch`. - - `class ProgramOutput` + - `:apply_patch` - - `id: String` + - `class BetaToolChoiceShell` - The unique ID of the program output item. + Forces the model to call the shell tool when a tool call is required. - - `call_id: String` + - `type: :shell` - The call ID of the program item. + The tool to call. Always `shell`. - - `result: String` + - `:shell` - The result produced by the program item. + - `tools: Array[BetaTool]` - - `status: :completed | :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. - The terminal status of the program output item. + We support the following categories of tools: - - `:completed` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](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. - - `:incomplete` + - `class BetaFunctionTool` - - `type: :program_output` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the item. Always `program_output`. + - `class BetaFileSearchTool` - - `:program_output` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `agent: Agent{ agent_name}` + - `class BetaComputerTool` - 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` + - `class BetaComputerUsePreviewTool` - 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). - - `class BetaResponseToolSearchCall` + - `class BetaWebSearchTool` - - `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 tool search call item. + - `class Mcp` - - `arguments: untyped` + 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). - Arguments used for the tool search call. + - `class CodeInterpreter` - - `call_id: String` + A tool that runs Python code to help generate a response to a prompt. - The unique ID of the tool search call generated by the model. + - `class ProgrammaticToolCalling` - - `execution: :server | :client` + - `class ImageGeneration` - Whether tool search was executed by the server or by the client. + A tool that generates images using the GPT image models. - - `:server` + - `class LocalShell` - - `:client` + A tool that allows the model to execute shell commands in a local environment. - - `status: :in_progress | :completed | :incomplete` + - `class BetaFunctionShellTool` - The status of the tool search call item that was recorded. + A tool that allows the model to execute shell commands. - - `:in_progress` + - `class BetaCustomTool` - - `: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` + - `class BetaNamespaceTool` - - `type: :tool_search_call` + Groups function/custom tools under a shared namespace. - The type of the item. Always `tool_search_call`. + - `class BetaToolSearchTool` - - `:tool_search_call` + Hosted or BYOT tool search configuration for deferred tools. - - `agent: Agent{ agent_name}` + - `class BetaWebSearchPreviewTool` - 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` + - `class BetaApplyPatchTool` - The canonical name of the agent that produced this item. + Allows the assistant to create, delete, or update files using unified diffs. - - `created_by: String` + - `top_p: Float` - The identifier of the actor that created the 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. - - `class BetaResponseToolSearchOutputItem` + We generally recommend altering this or `temperature` but not both. - - `id: String` + - `background: bool` - The unique ID of the tool search output item. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `call_id: String` + - `completed_at: Float` - The unique ID of the tool search call generated by the model. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `execution: :server | :client` + - `conversation: Conversation{ id}` - Whether tool search was executed by the server or by the client. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `:server` + - `id: String` - - `:client` + The unique ID of the conversation that this response was associated with. - - `status: :in_progress | :completed | :incomplete` + - `max_output_tokens: Integer` - The status of the tool search output item that was recorded. + 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: Integer` - - `: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: Moderation{ input, output}` - - `tools: Array[BetaTool]` + Moderation results for the response input and output, if moderated completions were requested. - The loaded tool definitions returned by tool search. + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `class BetaFunctionTool` + Moderation for the response input. - 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). + - `class ModerationResult` - - `name: String` + A moderation result produced for the response input or output. - The name of the function to call. + - `categories: Hash[Symbol, bool]` - - `parameters: Hash[Symbol, untyped]` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - A JSON schema object describing the parameters of the function. + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `strict: bool` + Which modalities of input are reflected by the score for each category. - Whether strict parameter validation is enforced for this function tool. + - `:text` - - `type: :function` + - `:image` - The type of the function tool. Always `function`. + - `category_scores: Hash[Symbol, Float]` - - `:function` + A dictionary of moderation categories to scores. - - `allowed_callers: Array[:direct | :programmatic]` + - `flagged: bool` - The tool invocation context(s). + A boolean indicating whether the content was flagged by any category. - - `:direct` + - `model: String` - - `:programmatic` + The moderation model that produced this result. - - `defer_loading: bool` + - `type: :moderation_result` - Whether this function is deferred and loaded via tool search. + The object type, which was always `moderation_result` for successful moderation results. - - `description: String` + - `:moderation_result` - A description of the function. Used by the model to determine whether or not to call the function. + - `class Error` - - `output_schema: Hash[Symbol, untyped]` + An error produced while attempting moderation for the response input or output. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `code: String` - - `class BetaFileSearchTool` + The error code. - 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: String` - - `type: :file_search` + The error message. - The type of the file search tool. Always `file_search`. + - `type: :error` - - `:file_search` + The object type, which was always `error` for moderation failures. - - `vector_store_ids: Array[String]` + - `:error` - The IDs of the vector stores to search. + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + Moderation for the response output. - A filter to apply. + - `class ModerationResult` - - `class ComparisonFilter` + A moderation result produced for the response input or output. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `categories: Hash[Symbol, bool]` - - `key: String` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The key to compare against the value. + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `type: :eq | :ne | :gt | 5 more` + Which modalities of input are reflected by the score for each category. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `:text` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `:image` - - `:eq` + - `category_scores: Hash[Symbol, Float]` - - `:ne` + A dictionary of moderation categories to scores. - - `:gt` + - `flagged: bool` - - `:gte` + A boolean indicating whether the content was flagged by any category. - - `:lt` + - `model: String` - - `:lte` + The moderation model that produced this result. - - `:in` + - `type: :moderation_result` - - `:nin` + The object type, which was always `moderation_result` for successful moderation results. - - `value: String | Float | bool | Array[untyped]` + - `:moderation_result` - The value to compare against the attribute key; supports string, number, or boolean types. + - `class Error` - - `String = String` + An error produced while attempting moderation for the response input or output. - - `Float = Float` + - `code: String` - - `UnionMember2 = bool` + The error code. - - `UnionMember3 = Array[untyped]` + - `message: String` - - `class CompoundFilter` + The error message. - Combine multiple filters using `and` or `or`. + - `type: :error` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The object type, which was always `error` for moderation failures. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `:error` - - `class ComparisonFilter` + - `previous_response_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 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`. - - `key: String` + - `prompt: BetaResponsePrompt` - The key to compare against the value. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `type: :eq | :ne | :gt | 5 more` + - `id: String` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The unique identifier of the prompt template to use. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:eq` + 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. - - `:ne` + - `String = String` - - `:gt` + - `class BetaResponseInputText` - - `:gte` + A text input to the model. - - `:lt` + - `class BetaResponseInputImage` - - `:lte` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:in` + - `class BetaResponseInputFile` - - `:nin` + A file input to the model. - - `value: String | Float | bool | Array[untyped]` + - `version: String` - The value to compare against the attribute key; supports string, number, or boolean types. + Optional version of the prompt template. - - `String = String` + - `prompt_cache_key: String` - - `Float = Float` + 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). - - `UnionMember2 = bool` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `UnionMember3 = Array[untyped]` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `UnionMember1 = untyped` + - `mode: :implicit | :explicit` - - `type: :and | :or` + Whether implicit prompt-cache breakpoints were enabled. - Type of operation: `and` or `or`. + - `:implicit` - - `:and` + - `:explicit` - - `:or` + - `ttl: :"30m"` - - `max_num_results: Integer` + The minimum lifetime applied to each cache breakpoint. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `:"30m"` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `prompt_cache_retention: :in_memory | :"24h"` - Ranking options for search. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + 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. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `embedding_weight: Float` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The weight of the embedding in the reciprocal ranking fusion. + - `:in_memory` - - `text_weight: Float` + - `:"24h"` - The weight of the text in the reciprocal ranking fusion. + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - - `ranker: :auto | :"default-2024-11-15"` + **gpt-5 and o-series models only** - The ranker to use for the file search. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `:auto` + - `context: :auto | :current_turn | :all_turns` - - `:"default-2024-11-15"` + 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. - - `score_threshold: Float` + - `: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. + - `:current_turn` - - `class BetaComputerTool` + - `:all_turns` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `effort: :none | :minimal | :low | 4 more` - - `type: :computer` + 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 computer tool. Always `computer`. + - `:none` - - `:computer` + - `:minimal` - - `class BetaComputerUsePreviewTool` + - `:low` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:medium` - - `display_height: Integer` + - `:high` - The height of the computer display. + - `:xhigh` - - `display_width: Integer` + - `:max` - The width of the computer display. + - `generate_summary: :auto | :concise | :detailed` - - `environment: :windows | :mac | :linux | 2 more` + **Deprecated:** use `summary` instead. - The type of computer environment to control. + 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`. - - `:windows` + - `:auto` - - `:mac` + - `:concise` - - `:linux` + - `:detailed` - - `:ubuntu` + - `mode: String | :standard | :pro` - - `:browser` + Controls the reasoning execution mode for the request. - - `type: :computer_use_preview` + When returned on a response, this is the effective execution mode. - The type of the computer use tool. Always `computer_use_preview`. + - `String = String` - - `:computer_use_preview` + - `Mode = :standard | :pro` - - `class BetaWebSearchTool` + Controls the reasoning execution mode for the request. - 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). + When returned on a response, this is the effective execution mode. - - `type: :web_search | :web_search_2025_08_26` + - `:standard` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `:pro` - - `:web_search` + - `summary: :auto | :concise | :detailed` - - `:web_search_2025_08_26` + 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`. - - `filters: Filters{ allowed_domains}` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Filters for the search. + - `:auto` - - `allowed_domains: Array[String]` + - `:concise` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `:detailed` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `safety_identifier: String` - - `search_context_size: :low | :medium | :high` + 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). - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `service_tier: :auto | :default | :flex | 2 more` - - `:low` + Specifies the processing type used for serving the request. - - `:medium` + - 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'. - - `:high` + 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. - - `user_location: UserLocation{ city, country, region, 2 more}` + - `:auto` - The approximate location of the user. + - `:default` - - `city: String` + - `:flex` - Free text input for the city of the user, e.g. `San Francisco`. + - `:scale` - - `country: String` + - `:priority` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `status: BetaResponseStatus` - - `region: String` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - Free text input for the region of the user, e.g. `California`. + - `:completed` - - `timezone: String` + - `:failed` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:in_progress` - - `type: :approximate` + - `:cancelled` - The type of location approximation. Always `approximate`. + - `:queued` - - `:approximate` + - `:incomplete` - - `class Mcp` + - `text: BetaResponseTextConfig` - 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). + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `server_label: String` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - A label for this MCP server, used to identify it in tool calls. + - `format_: BetaResponseFormatTextConfig` - - `type: :mcp` + An object specifying the format that the model must output. - The type of the MCP tool. Always `mcp`. + 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). - - `:mcp` + The default format is `{ "type": "text" }` with no additional options. - - `allowed_callers: Array[:direct | :programmatic]` + **Not recommended for gpt-4o and newer models:** - The tool invocation context(s). + 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` + - `class Text` - - `:programmatic` + Default response format. Used to generate text responses. - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `type: :text` - List of allowed tool names or a filter object. + The type of response format being defined. Always `text`. - - `McpAllowedTools = Array[String]` + - `:text` - A string array of allowed tool names + - `class BetaResponseFormatTextJSONSchemaConfig` - - `class McpToolFilter` + 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: bool` + 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: Hash[Symbol, untyped]` - - `tool_names: Array[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` - - `authorization: String` + The type of response format being defined. Always `json_schema`. - 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. + - `:json_schema` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `description: 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 description of what the response format is for, used by the model to + determine how to respond in the format. - Currently supported `connector_id` values are: + - `strict: bool` - - 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` + 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). - - `:connector_dropbox` + - `class JSONObject` - - `:connector_gmail` + 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. - - `:connector_googlecalendar` + - `type: :json_object` - - `:connector_googledrive` + The type of response format being defined. Always `json_object`. - - `:connector_microsoftteams` + - `:json_object` - - `:connector_outlookcalendar` + - `verbosity: :low | :medium | :high` - - `:connector_outlookemail` + 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`. - - `:connector_sharepoint` + - `:low` - - `defer_loading: bool` + - `:medium` - Whether this MCP tool is deferred and discovered via tool search. + - `:high` - - `headers: Hash[Symbol, String]` + - `top_logprobs: Integer` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + 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. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `truncation: :auto | :disabled` - Specify which of the MCP server's tools require approval. + The truncation strategy to use for the model response. - - `class McpToolApprovalFilter` + - `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. - 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: Always{ read_only, tool_names}` + - `:disabled` - A filter object to specify which tools are allowed. + - `usage: BetaResponseUsage` - - `read_only: bool` + 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: Integer` - - `tool_names: Array[String]` + The number of input tokens. - List of allowed tool names. + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - - `never: Never{ read_only, tool_names}` + A detailed breakdown of the input tokens. - A filter object to specify which tools are allowed. + - `cache_write_tokens: Integer` - - `read_only: bool` + 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: Integer` - - `tool_names: Array[String]` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - List of allowed tool names. + - `output_tokens: Integer` - - `McpToolApprovalSetting = :always | :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: OutputTokensDetails{ reasoning_tokens}` - - `:always` + A detailed breakdown of the output tokens. - - `:never` + - `reasoning_tokens: Integer` - - `server_description: String` + The number of reasoning tokens. - Optional description of the MCP server, used to provide more context. + - `total_tokens: Integer` - - `server_url: 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. + - `user: String` - - `tunnel_id: String` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `sequence_number: Integer` - - `class CodeInterpreter` + The sequence number for this event. - A tool that runs Python code to help generate a response to a prompt. + - `type: :"response.created"` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + The type of the event. Always `response.created`. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `:"response.created"` - - `String = String` + - `agent: Agent{ agent_name}` - The container ID. + The agent that owns this multi-agent streaming event. - - `class CodeInterpreterToolAuto` + - `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` +### Beta Response Custom Tool Call - Always `auto`. +- `class BetaResponseCustomToolCall` - - `:auto` + A call to a custom tool created by the model. - - `file_ids: Array[String]` + - `call_id: String` - An optional list of uploaded files to make available to your code. + An identifier used to map this custom tool call to a tool call output. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `input: String` - The memory limit for the code interpreter container. + The input for the custom tool call generated by the model. - - `:"1g"` + - `name: String` - - `:"4g"` + The name of the custom tool being called. - - `:"16g"` + - `type: :custom_tool_call` - - `:"64g"` + The type of the custom tool call. Always `custom_tool_call`. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:custom_tool_call` - Network access policy for the container. + - `id: String` - - `class BetaContainerNetworkPolicyDisabled` + The unique ID of the custom tool call in the OpenAI platform. - - `type: :disabled` + - `agent: Agent{ agent_name}` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `:disabled` + - `agent_name: String` - - `class BetaContainerNetworkPolicyAllowlist` + The canonical name of the agent that produced this item. - - `allowed_domains: Array[String]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A list of allowed domains when type is `allowlist`. + The execution context that produced this tool call. - - `type: :allowlist` + - `class Direct` - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: :direct` - - `:allowlist` + - `:direct` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `class Program` - Optional domain-scoped secrets for allowlisted domains. + - `caller_id: String` - - `domain: String` + The call ID of the program item that produced this tool call. - The domain associated with the secret. + - `type: :program` - - `name: String` + - `:program` - The name of the secret to inject for the domain. + - `namespace: String` - - `value: String` + The namespace of the custom tool being called. - The secret value to inject for the domain. +### Beta Response Custom Tool Call Input Delta Event - - `type: :code_interpreter` +- `class BetaResponseCustomToolCallInputDeltaEvent` - The type of the code interpreter tool. Always `code_interpreter`. + Event representing a delta (partial update) to the input of a custom tool call. - - `:code_interpreter` + - `delta: String` - - `allowed_callers: Array[:direct | :programmatic]` + The incremental input data (delta) for the custom tool call. - The tool invocation context(s). + - `item_id: String` - - `:direct` + Unique identifier for the API item associated with this event. - - `:programmatic` + - `output_index: Integer` - - `class ProgrammaticToolCalling` + The index of the output this delta applies to. - - `type: :programmatic_tool_calling` + - `sequence_number: Integer` - The type of the tool. Always `programmatic_tool_calling`. + The sequence number of this event. - - `:programmatic_tool_calling` + - `type: :"response.custom_tool_call_input.delta"` - - `class ImageGeneration` + The event type identifier. - A tool that generates images using the GPT image models. + - `:"response.custom_tool_call_input.delta"` - - `type: :image_generation` + - `agent: Agent{ 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: :generate | :edit | :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 Custom Tool Call Input Done Event - - `:generate` +- `class BetaResponseCustomToolCallInputDoneEvent` - - `:edit` + Event indicating that input for a custom tool call is complete. - - `:auto` + - `input: String` - - `background: :transparent | :opaque | :auto` + The complete input data for the custom tool call. - 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. + - `item_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. + Unique identifier for the API item associated with this event. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `output_index: Integer` - - `:transparent` + The index of the output this event applies to. - - `:opaque` + - `sequence_number: Integer` - - `:auto` + The sequence number of this event. - - `input_fidelity: :high | :low` + - `type: :"response.custom_tool_call_input.done"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The event type identifier. - - `:high` + - `:"response.custom_tool_call_input.done"` - - `:low` + - `agent: Agent{ agent_name}` - - `input_image_mask: InputImageMask{ file_id, image_url}` + The agent that owns this multi-agent streaming event. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `agent_name: String` - - `file_id: String` + The canonical name of the agent that produced this item. - File ID for the mask image. +### Beta Response Custom Tool Call Item - - `image_url: String` +- `class BetaResponseCustomToolCallItem` - Base64-encoded mask image. + A call to a custom tool created by the model. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `id: String` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the custom tool call item. - - `String = String` + - `status: :in_progress | :completed | :incomplete` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The image generation model to use. Default: `gpt-image-1`. + - `:in_progress` - - `:"gpt-image-1"` + - `:completed` - - `:"gpt-image-1-mini"` + - `:incomplete` - - `:"gpt-image-2"` + - `created_by: String` - - `:"gpt-image-2-2026-04-21"` + The identifier of the actor that created the item. - - `:"gpt-image-1.5"` +### Beta Response Custom Tool Call Output - - `:"chatgpt-image-latest"` +- `class BetaResponseCustomToolCallOutput` - - `moderation: :auto | :low` + The output of a custom tool call from your code, being sent back to the model. - Moderation level for the generated image. Default: `auto`. + - `call_id: String` - - `:auto` + The call ID, used to map this custom tool call output to a custom tool call. - - `:low` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `output_compression: Integer` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Compression level for the output image. Default: 100. + - `String = String` - - `output_format: :png | :webp | :jpeg` + A string of the output of the custom tool call. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:png` + Text, image, or file output of the custom tool call. - - `:webp` + - `class BetaResponseInputText` - - `:jpeg` + A text input to the model. - - `partial_images: Integer` + - `text: String` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The text input to the model. - - `quality: :low | :medium | :high | :auto` + - `type: :input_text` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the input item. Always `input_text`. - - `:low` + - `:input_text` - - `:medium` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:high` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:auto` + - `mode: :explicit` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + The breakpoint mode. Always `explicit`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `:explicit` - - `String = String` + - `class BetaResponseInputImage` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `detail: :low | :high | :auto | :original` - - `:"1024x1024"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:"1024x1536"` + - `:low` - - `:"1536x1024"` + - `:high` - `:auto` - - `class LocalShell` - - A tool that allows the model to execute shell commands in a local environment. + - `:original` - - `type: :local_shell` + - `type: :input_image` - The type of the local shell tool. Always `local_shell`. + The type of the input item. Always `input_image`. - - `:local_shell` + - `:input_image` - - `class BetaFunctionShellTool` + - `file_id: String` - A tool that allows the model to execute shell commands. + The ID of the file to be sent to the model. - - `type: :shell` + - `image_url: String` - The type of the shell tool. Always `shell`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `:shell` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `allowed_callers: Array[:direct | :programmatic]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The tool invocation context(s). + - `mode: :explicit` - - `:direct` + The breakpoint mode. Always `explicit`. - - `:programmatic` + - `:explicit` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `class BetaResponseInputFile` - - `class BetaContainerAuto` + A file input to the model. - - `type: :container_auto` + - `type: :input_file` - Automatically creates a container for this request + The type of the input item. Always `input_file`. - - `:container_auto` + - `:input_file` - - `file_ids: Array[String]` + - `detail: :auto | :low | :high` - An optional list of uploaded files to make available to your code. + 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`. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:auto` - The memory limit for the container. + - `:low` - - `:"1g"` + - `:high` - - `:"4g"` + - `file_data: String` - - `:"16g"` + The content of the file to be sent to the model. - - `:"64g"` + - `file_id: String` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + The ID of the file to be sent to the model. - Network access policy for the container. + - `file_url: String` - - `class BetaContainerNetworkPolicyDisabled` + The URL of the file to be sent to the model. - - `class BetaContainerNetworkPolicyAllowlist` + - `filename: String` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + The name of the file to be sent to the model. - An optional list of skills referenced by id or inline data. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class BetaSkillReference` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `skill_id: String` + - `mode: :explicit` - The ID of the referenced skill. + The breakpoint mode. Always `explicit`. - - `type: :skill_reference` + - `:explicit` - References a skill created with the /v1/skills endpoint. + - `type: :custom_tool_call_output` - - `:skill_reference` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `version: String` + - `:custom_tool_call_output` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `id: String` - - `class BetaInlineSkill` + The unique ID of the custom tool call output in the OpenAI platform. - - `description: String` + - `agent: Agent{ 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. - - `source: BetaInlineSkillSource` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Inline skill payload + The execution context that produced this tool call. - - `data: String` + - `class Direct` - Base64-encoded skill zip bundle. + - `type: :direct` - - `media_type: :"application/zip"` + The caller type. Always `direct`. - The media type of the inline skill payload. Must be `application/zip`. + - `:direct` - - `:"application/zip"` + - `class Program` - - `type: :base64` + - `caller_id: String` - The type of the inline skill source. Must be `base64`. + The call ID of the program item that produced this tool call. - - `:base64` + - `type: :program` - - `type: :inline` + The caller type. Always `program`. - Defines an inline skill for this request. + - `:program` - - `:inline` +### Beta Response Custom Tool Call Output Item - - `class BetaLocalEnvironment` +- `class BetaResponseCustomToolCallOutputItem` - - `type: :local` + The output of a custom tool call from your code, being sent back to the model. - Use a local computer environment. + - `id: String` - - `:local` + The unique ID of the custom tool call output item. - - `skills: Array[BetaLocalSkill]` + - `status: :in_progress | :completed | :incomplete` - An optional list of skills. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `description: String` + - `:in_progress` - The description of the skill. + - `:completed` - - `name: String` + - `:incomplete` - The name of the skill. + - `created_by: String` - - `path: String` + The identifier of the actor that created the item. - The path to the directory containing the skill. +### Beta Response Error - - `class BetaContainerReference` +- `class BetaResponseError` - - `container_id: String` + An error object returned when the model fails to generate a Response. - The ID of the referenced container. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `type: :container_reference` + The error code for the response. - References a container created with the /v1/containers endpoint + - `:server_error` - - `:container_reference` + - `:rate_limit_exceeded` - - `class BetaCustomTool` + - `:invalid_prompt` - 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) + - `:bio_policy` - - `name: String` + - `:vector_store_timeout` - The name of the custom tool, used to identify it in tool calls. + - `:invalid_image` - - `type: :custom` + - `:invalid_image_format` - The type of the custom tool. Always `custom`. + - `:invalid_base64_image` - - `:custom` + - `:invalid_image_url` - - `allowed_callers: Array[:direct | :programmatic]` + - `:image_too_large` - The tool invocation context(s). + - `:image_too_small` - - `:direct` + - `:image_parse_error` - - `:programmatic` + - `:image_content_policy_violation` - - `defer_loading: bool` + - `:invalid_image_mode` - Whether this tool should be deferred and discovered via tool search. + - `:image_file_too_large` - - `description: String` + - `:unsupported_image_media_type` - Optional description of the custom tool, used to provide more context. + - `:empty_image_file` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `:failed_to_download_image` - The input format for the custom tool. Default is unconstrained text. + - `:image_file_not_found` - - `class Text` + - `message: String` - Unconstrained free-form text. + A human-readable description of the error. - - `type: :text` +### Beta Response Error Event - Unconstrained text format. Always `text`. +- `class BetaResponseErrorEvent` - - `:text` + Emitted when an error occurs. - - `class Grammar` + - `code: String` - A grammar defined by the user. + The error code. - - `definition: String` + - `message: String` - The grammar definition. + The error message. - - `syntax: :lark | :regex` + - `param: String` - The syntax of the grammar definition. One of `lark` or `regex`. + The error parameter. - - `:lark` + - `sequence_number: Integer` - - `:regex` + The sequence number of this event. - - `type: :grammar` + - `type: :error` - Grammar format. Always `grammar`. + The type of the event. Always `error`. - - `:grammar` + - `:error` - - `class BetaNamespaceTool` + - `agent: Agent{ 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` +### Beta Response Failed Event - The namespace name used in tool calls (for example, `crm`). +- `class BetaResponseFailedEvent` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + An event that is emitted when a response fails. - The function/custom tools available inside this namespace. + - `response: BetaResponse` - - `class Function` + The response that failed. - - `name: String` + - `id: String` - - `type: :function` + Unique identifier for this Response. - - `:function` + - `created_at: Float` - - `allowed_callers: Array[:direct | :programmatic]` + Unix timestamp (in seconds) of when this Response was created. - The tool invocation context(s). + - `error: BetaResponseError` - - `:direct` + An error object returned when the model fails to generate a Response. - - `:programmatic` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `defer_loading: bool` + The error code for the response. - Whether this function should be deferred and discovered via tool search. + - `:server_error` - - `description: String` + - `:rate_limit_exceeded` - - `output_schema: Hash[Symbol, untyped]` + - `:invalid_prompt` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `:bio_policy` - - `parameters: untyped` + - `:vector_store_timeout` - - `strict: bool` + - `:invalid_image` - 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. + - `:invalid_image_format` - - `class BetaCustomTool` + - `:invalid_base64_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) + - `:invalid_image_url` - - `type: :namespace` + - `:image_too_large` - The type of the tool. Always `namespace`. + - `:image_too_small` - - `:namespace` + - `:image_parse_error` - - `class BetaToolSearchTool` + - `:image_content_policy_violation` - Hosted or BYOT tool search configuration for deferred tools. + - `:invalid_image_mode` - - `type: :tool_search` + - `:image_file_too_large` - The type of the tool. Always `tool_search`. + - `:unsupported_image_media_type` - - `:tool_search` + - `:empty_image_file` - - `description: String` + - `:failed_to_download_image` - Description shown to the model for a client-executed tool search tool. + - `:image_file_not_found` - - `execution: :server | :client` + - `message: String` - Whether tool search is executed by the server or by the client. + A human-readable description of the error. - - `:server` + - `incomplete_details: IncompleteDetails{ reason}` - - `:client` + Details about why the response is incomplete. - - `parameters: untyped` + - `reason: :max_output_tokens | :content_filter` - Parameter schema for a client-executed tool search tool. + The reason why the response is incomplete. - - `class BetaWebSearchPreviewTool` + - `:max_output_tokens` - 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). + - `:content_filter` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `instructions: String | Array[BetaResponseInputItem]` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + A system (or developer) message inserted into the model's context. - - `:web_search_preview` + 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. - - `:web_search_preview_2025_03_11` + - `String = String` - - `search_content_types: Array[:text | :image]` + A text input to the model, equivalent to a text input with the + `developer` role. - - `:text` + - `InputItemList = Array[BetaResponseInputItem]` - - `:image` + A list of one or many input items to the model, containing + different content types. - - `search_context_size: :low | :medium | :high` + - `class BetaEasyInputMessage` - High 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 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. - - `:low` + - `content: String | BetaResponseInputMessageContentList` - - `:medium` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `:high` + - `String = String` - - `user_location: UserLocation{ type, city, country, 2 more}` + A text input to the model. - The user's location. + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `type: :approximate` + A list of one or many input items to the model, containing different content + types. - The type of location approximation. Always `approximate`. + - `class BetaResponseInputText` - - `:approximate` + A text input to the model. - - `city: String` + - `text: String` - Free text input for the city of the user, e.g. `San Francisco`. + The text input to the model. - - `country: String` + - `type: :input_text` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of the input item. Always `input_text`. - - `region: String` + - `:input_text` - Free text input for the region of the user, e.g. `California`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `timezone: 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` - - `class BetaApplyPatchTool` + The breakpoint mode. Always `explicit`. - Allows the assistant to create, delete, or update files using unified diffs. + - `:explicit` - - `type: :apply_patch` + - `class BetaResponseInputImage` - The type of the tool. Always `apply_patch`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:apply_patch` + - `detail: :low | :high | :auto | :original` - - `allowed_callers: Array[:direct | :programmatic]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The tool invocation context(s). + - `:low` - - `:direct` + - `:high` - - `:programmatic` + - `:auto` - - `type: :tool_search_output` + - `:original` - The type of the item. Always `tool_search_output`. + - `type: :input_image` - - `:tool_search_output` + The type of the input item. Always `input_image`. - - `agent: Agent{ agent_name}` + - `:input_image` - The agent that produced this item. + - `file_id: String` - - `agent_name: String` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `image_url: String` - - `created_by: String` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The identifier of the actor that created the item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class AdditionalTools` + Marks the exact end of a reusable 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 additional tools item. + The breakpoint mode. Always `explicit`. - - `role: :unknown | :user | :assistant | 5 more` + - `:explicit` - The role that provided the additional tools. + - `class BetaResponseInputFile` - - `:unknown` + A file input to the model. - - `:user` + - `type: :input_file` - - `:assistant` + The type of the input item. Always `input_file`. - - `:system` + - `:input_file` - - `:critic` + - `detail: :auto | :low | :high` - - `:discriminator` + 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`. - - `:developer` + - `:auto` - - `:tool` + - `:low` - - `tools: Array[BetaTool]` + - `:high` - The additional tool definitions made available at this item. + - `file_data: String` - - `class BetaFunctionTool` + The content of the file to be sent to the model. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `file_id: String` - - `class BetaFileSearchTool` + The ID of the file to be sent to the model. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `file_url: String` - - `class BetaComputerTool` + The URL of the file to be sent to the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `filename: String` - - `class BetaComputerUsePreviewTool` + The name of the file to be sent to the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class BetaWebSearchTool` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `mode: :explicit` - - `class Mcp` + The breakpoint mode. Always `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). + - `:explicit` - - `class CodeInterpreter` + - `role: :user | :assistant | :system | :developer` - A tool that runs Python code to help generate a response to a prompt. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `class ProgrammaticToolCalling` + - `:user` - - `class ImageGeneration` + - `:assistant` - A tool that generates images using the GPT image models. + - `:system` - - `class LocalShell` + - `:developer` - A tool that allows the model to execute shell commands in a local environment. + - `phase: :commentary | :final_answer` - - `class BetaFunctionShellTool` + 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 tool that allows the model to execute shell commands. + - `:commentary` - - `class BetaCustomTool` + - `:final_answer` - 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` - - `class BetaNamespaceTool` + The type of the message input. Always `message`. - Groups function/custom tools under a shared namespace. + - `:message` - - `class BetaToolSearchTool` + - `class Message` - Hosted or BYOT tool search configuration for deferred tools. + 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. - - `class BetaWebSearchPreviewTool` + - `content: BetaResponseInputMessageContentList` - 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 one or many input items to the model, containing different content + types. - - `class BetaApplyPatchTool` + - `role: :user | :system | :developer` - Allows the assistant to create, delete, or update files using unified diffs. + The role of the message input. One of `user`, `system`, or `developer`. - - `type: :additional_tools` + - `:user` - The type of the item. Always `additional_tools`. + - `:system` - - `:additional_tools` + - `:developer` - `agent: Agent{ agent_name}` @@ -49166,196 +59477,189 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `id: String` - - The unique ID of the compaction item. - - - `encrypted_content: String` + - `status: :in_progress | :completed | :incomplete` - The encrypted content that was produced by compaction. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: :compaction` + - `:in_progress` - The type of the item. Always `compaction`. + - `:completed` - - `:compaction` + - `:incomplete` - - `agent: Agent{ agent_name}` + - `type: :message` - The agent that produced this item. + The type of the message input. Always set to `message`. - - `agent_name: String` + - `:message` - The canonical name of the agent that produced this item. + - `class BetaResponseOutputMessage` - - `created_by: String` + An output message from the model. - The identifier of the actor that created the item. + - `id: String` - - `class ImageGenerationCall` + The unique ID of the output message. - An image generation request made by the model. + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - - `id: String` + The content of the output message. - The unique ID of the image generation call. + - `class BetaResponseOutputText` - - `result: String` + A text output from the model. - The generated image encoded in base64. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `status: :in_progress | :completed | :generating | :failed` + The annotations of the text output. - The status of the image generation call. + - `class FileCitation` - - `:in_progress` + A citation to a file. - - `:completed` + - `file_id: String` - - `:generating` + The ID of the file. - - `:failed` + - `filename: String` - - `type: :image_generation_call` + The filename of the file cited. - The type of the image generation call. Always `image_generation_call`. + - `index: Integer` - - `:image_generation_call` + The index of the file in the list of files. - - `agent: Agent{ 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. + - `class URLCitation` - - `class BetaResponseCodeInterpreterToolCall` + A citation for a web resource used to generate a model response. - A tool call to run code. + - `end_index: Integer` - - `id: String` + The index of the last character of the URL citation in the message. - The unique ID of the code interpreter tool call. + - `start_index: Integer` - - `code: String` + The index of the first character of the URL citation in the message. - The code to run, or null if not available. + - `title: String` - - `container_id: String` + The title of the web resource. - The ID of the container used to run the code. + - `type: :url_citation` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + The type of the URL citation. Always `url_citation`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `:url_citation` - - `class Logs` + - `url: String` - The logs output from the code interpreter. + The URL of the web resource. - - `logs: String` + - `class ContainerFileCitation` - The logs output from the code interpreter. + A citation for a container file used to generate a model response. - - `type: :logs` + - `container_id: String` - The type of the output. Always `logs`. + The ID of the container file. - - `:logs` + - `end_index: Integer` - - `class Image` + The index of the last character of the container file citation in the message. - The image output from the code interpreter. + - `file_id: String` - - `type: :image` + The ID of the file. - The type of the output. Always `image`. + - `filename: String` - - `:image` + The filename of the container file cited. - - `url: String` + - `start_index: Integer` - The URL of the image output from the code interpreter. + The index of the first character of the container file citation in the message. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `type: :container_file_citation` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The type of the container file citation. Always `container_file_citation`. - - `:in_progress` + - `:container_file_citation` - - `:completed` + - `class FilePath` - - `:incomplete` + A path to a file. - - `:interpreting` + - `file_id: String` - - `:failed` + The ID of the file. - - `type: :code_interpreter_call` + - `index: Integer` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The index of the file in the list of files. - - `:code_interpreter_call` + - `type: :file_path` - - `agent: Agent{ agent_name}` + The type of the file path. Always `file_path`. - The agent that produced this item. + - `:file_path` - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + The text output from the model. - - `class LocalShellCall` + - `type: :output_text` - A tool call to run a command on the local shell. + The type of the output text. Always `output_text`. - - `id: String` + - `:output_text` - The unique ID of the local shell call. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `action: Action{ command, env, type, 3 more}` + - `token: String` - Execute a shell command on the server. + - `bytes: Array[Integer]` - - `command: Array[String]` + - `logprob: Float` - The command to run. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `env: Hash[Symbol, String]` + - `token: String` - Environment variables to set for the command. + - `bytes: Array[Integer]` - - `type: :exec` + - `logprob: Float` - The type of the local shell action. Always `exec`. + - `class BetaResponseOutputRefusal` - - `:exec` + A refusal from the model. - - `timeout_ms: Integer` + - `refusal: String` - Optional timeout in milliseconds for the command. + The refusal explanation from the model. - - `user: String` + - `type: :refusal` - Optional user to run the command as. + The type of the refusal. Always `refusal`. - - `working_directory: String` + - `:refusal` - Optional working directory to run the command in. + - `role: :assistant` - - `call_id: String` + The role of the output message. Always `assistant`. - The unique ID of the local shell tool call generated by the model. + - `:assistant` - `status: :in_progress | :completed | :incomplete` - The status of the local shell call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `:in_progress` @@ -49363,11 +59667,11 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :local_shell_call` + - `type: :message` - The type of the local shell call. Always `local_shell_call`. + The type of the output message. Always `message`. - - `:local_shell_call` + - `:message` - `agent: Agent{ agent_name}` @@ -49377,23 +59681,49 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput` + - `phase: :commentary | :final_answer` - The output of a local shell 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. + + - `:commentary` + + - `:final_answer` + + - `class BetaResponseFileSearchToolCall` + + 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 local shell tool call generated by the model. + The unique ID of the file search tool call. - - `output: String` + - `queries: Array[String]` - A JSON string of the output of the local shell tool call. + The queries used to search for files. - - `type: :local_shell_call_output` + - `status: :in_progress | :searching | :completed | 2 more` - The type of the local shell tool call output. Always `local_shell_call_output`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `:local_shell_call_output` + - `: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: Agent{ agent_name}` @@ -49403,71 +59733,73 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - `:completed` + The results of the file search tool call. - - `:incomplete` + - `attributes: Hash[Symbol, String | Float | bool]` - - `class BetaResponseFunctionShellToolCall` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - A tool call that executes one or more shell commands in a managed environment. + - `String = String` - - `id: String` + - `Float = Float` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `UnionMember2 = bool` - - `action: Action{ commands, max_output_length, timeout_ms}` + - `file_id: String` - The shell commands and limits that describe how to run the tool call. + The unique ID of the file. - - `commands: Array[String]` + - `filename: String` - - `max_output_length: Integer` + The name of the file. - Optional maximum number of characters to return from each command. + - `score: Float` - - `timeout_ms: Integer` + The relevance score of the file - a value between 0 and 1. - Optional timeout in milliseconds for the commands. + - `text: String` - - `call_id: String` + The text that was retrieved from the file. - The unique ID of the shell tool call generated by the model. + - `class BetaResponseComputerToolCall` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + 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. - Represents the use of a local environment to perform shell actions. + - `id: String` - - `class BetaResponseLocalEnvironment` + The unique ID of the computer call. - Represents the use of a local environment to perform shell actions. + - `call_id: String` - - `type: :local` + An identifier used when responding to the tool call with output. - The environment type. Always `local`. + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `:local` + The pending safety checks for the computer call. - - `class BetaResponseContainerReference` + - `id: String` - Represents a container created with /v1/containers. + The ID of the pending safety check. - - `container_id: String` + - `code: String` - - `type: :container_reference` + The type of the pending safety check. - The environment type. Always `container_reference`. + - `message: String` - - `:container_reference` + Details about the pending safety check. - `status: :in_progress | :completed | :incomplete` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -49475,231 +59807,247 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :shell_call` + - `type: :computer_call` - The type of the item. Always `shell_call`. + The type of the computer call. Always `computer_call`. - - `:shell_call` + - `:computer_call` - - `agent: Agent{ agent_name}` + - `action: BetaComputerAction` - The agent that produced this item. + A click action. - - `agent_name: String` + - `class Click` - The canonical name of the agent that produced this item. + A click action. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `button: :left | :right | :wheel | 2 more` - The execution context that produced this tool call. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class Direct` + - `:left` - - `type: :direct` + - `:right` - - `:direct` + - `:wheel` - - `class Program` + - `:back` - - `caller_id: String` + - `:forward` - The call ID of the program item that produced this tool call. + - `type: :click` - - `type: :program` + Specifies the event type. For a click action, this property is always `click`. - - `:program` + - `:click` - - `created_by: String` + - `x: Integer` - The ID of the entity that created this tool call. + The x-coordinate where the click occurred. - - `class BetaResponseFunctionShellToolCallOutput` + - `y_: Integer` - The output of a shell tool call that was emitted. + The y-coordinate where the click occurred. - - `id: String` + - `keys: Array[String]` - The unique ID of the shell call output. Populated when this item is returned via API. + The keys being held while clicking. - - `call_id: String` + - `class DoubleClick` - The unique ID of the shell tool call generated by the model. + A double click action. - - `max_output_length: Integer` + - `keys: Array[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 keys being held while double-clicking. - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `type: :double_click` - An array of shell call output contents + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `:double_click` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `x: Integer` - - `class Timeout` + The x-coordinate where the double click occurred. - Indicates that the shell call exceeded its configured time limit. + - `y_: Integer` - - `type: :timeout` + The y-coordinate where the double click occurred. - The outcome type. Always `timeout`. + - `class Drag` - - `:timeout` + A drag action. - - `class Exit` + - `path: Array[Path{ x, y_}]` - Indicates that the shell commands finished and returned an exit code. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `exit_code: Integer` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Exit code from the shell process. + - `x: Integer` - - `type: :exit` + The x-coordinate. - The outcome type. Always `exit`. + - `y_: Integer` - - `:exit` + The y-coordinate. - - `stderr: String` + - `type: :drag` - The standard error output that was captured. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `stdout: String` + - `:drag` - The standard output that was captured. + - `keys: Array[String]` - - `created_by: String` + The keys being held while dragging the mouse. - The identifier of the actor that created the item. + - `class Keypress` - - `status: :in_progress | :completed | :incomplete` + A collection of keypresses the model would like to perform. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `keys: Array[String]` - - `:in_progress` + 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: :shell_call_output` + - `:keypress` - The type of the shell call output. Always `shell_call_output`. + - `class Move` - - `:shell_call_output` + A mouse move action. - - `agent: Agent{ 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: Integer` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The x-coordinate to move to. - The execution context that produced this tool call. + - `y_: Integer` - - `class Direct` + The y-coordinate to move to. - - `type: :direct` + - `keys: Array[String]` - - `:direct` + The keys being held while moving the mouse. - - `class Program` + - `class Screenshot` - - `caller_id: String` + A screenshot action. - The call ID of the program item that produced this tool call. + - `type: :screenshot` - - `type: :program` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `:program` + - `:screenshot` - - `created_by: String` + - `class Scroll` - The identifier of the actor that created the item. + A scroll action. - - `class BetaResponseApplyPatchToolCall` + - `scroll_x: Integer` - A tool call that applies file diffs by creating, deleting, or updating files. + The horizontal scroll distance. - - `id: String` + - `scroll_y: Integer` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The vertical scroll distance. - - `call_id: String` + - `type: :scroll` - The unique ID of the apply patch tool call generated by the model. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `:scroll` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `x: Integer` - - `class CreateFile` + The x-coordinate where the scroll occurred. - Instruction describing how to create a file via the apply_patch tool. + - `y_: Integer` - - `diff: String` + The y-coordinate where the scroll occurred. - Diff to apply. + - `keys: Array[String]` - - `path: String` + The keys being held while scrolling. - Path of the file to create. + - `class Type` - - `type: :create_file` + An action to type in text. - Create a new file with the provided diff. + - `text: String` - - `:create_file` + The text to type. - - `class DeleteFile` + - `type: :type` - Instruction describing how to delete a file via the apply_patch tool. + Specifies the event type. For a type action, this property is always set to `type`. - - `path: String` + - `:type` - Path of the file to delete. + - `class Wait` - - `type: :delete_file` + A wait action. - Delete the specified file. + - `type: :wait` - - `:delete_file` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class UpdateFile` + - `:wait` - Instruction describing how to update a file via the apply_patch tool. + - `actions: BetaComputerActionList` - - `diff: String` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Diff to apply. + - `class Click` - - `path: String` + A click action. - Path of the file to update. + - `class DoubleClick` - - `type: :update_file` + A double click action. - Update an existing file with the provided diff. + - `class Drag` - - `:update_file` + A drag action. - - `status: :in_progress | :completed` + - `class Keypress` - The status of the apply patch tool call. One of `in_progress` or `completed`. + A collection of keypresses the model would like to perform. - - `:in_progress` + - `class Move` - - `:completed` + A mouse move action. - - `type: :apply_patch_call` + - `class Screenshot` - The type of the item. Always `apply_patch_call`. + A screenshot action. - - `:apply_patch_call` + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. - `agent: Agent{ agent_name}` @@ -49709,55 +60057,58 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class ComputerCallOutput` - The execution context that produced this tool call. + The output of a computer tool call. - - `class Direct` + - `call_id: String` - - `type: :direct` + The ID of the computer tool call that produced the output. - - `:direct` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `class Program` + A computer screenshot image used with the computer use tool. - - `caller_id: String` + - `type: :computer_screenshot` - The call ID of the program item that produced this tool call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: :program` + - `:computer_screenshot` - - `:program` + - `file_id: String` - - `created_by: String` + The identifier of an uploaded file that contains the screenshot. - The ID of the entity that created this tool call. + - `image_url: String` - - `class BetaResponseApplyPatchToolCallOutput` + The URL of the screenshot image. - The output emitted by an apply patch tool call. + - `type: :computer_call_output` - - `id: String` + The type of the computer tool call output. Always `computer_call_output`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:computer_call_output` - - `call_id: String` + - `id: String` - The unique ID of the apply patch tool call generated by the model. + The ID of the computer tool call output. - - `status: :completed | :failed` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The safety checks reported by the API that have been acknowledged by the developer. - - `:completed` + - `id: String` - - `:failed` + The ID of the pending safety check. - - `type: :apply_patch_call_output` + - `code: String` - The type of the item. Always `apply_patch_call_output`. + The type of the pending safety check. - - `:apply_patch_call_output` + - `message: String` + + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -49767,979 +60118,986 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `status: :in_progress | :completed | :incomplete` - The execution context that produced this tool call. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `class Direct` + - `:in_progress` - - `type: :direct` + - `:completed` - - `:direct` + - `:incomplete` - - `class Program` + - `class BetaResponseFunctionWebSearch` - - `caller_id: 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 call ID of the program item that produced this tool call. + - `id: String` - - `type: :program` + The unique ID of the web search tool call. - - `:program` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `created_by: 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 entity that created this tool call output. + - `class Search` - - `output: String` + Action type "search" - Performs a web search query. - Optional textual output returned by the apply patch tool. + - `type: :search` - - `class McpCall` + The action type. - An invocation of a tool on an MCP server. + - `:search` - - `id: String` + - `queries: Array[String]` - The unique ID of the tool call. + The search queries. - - `arguments: String` + - `query: String` - A JSON string of the arguments passed to the tool. + The search query. - - `name: String` + - `sources: Array[Source{ type, url}]` - The name of the tool that was run. + The sources used in the search. - - `server_label: String` + - `type: :url` - The label of the MCP server running the tool. + The type of source. Always `url`. - - `type: :mcp_call` + - `:url` - The type of the item. Always `mcp_call`. + - `url: String` - - `:mcp_call` + The URL of the source. - - `agent: Agent{ agent_name}` + - `class OpenPage` - The agent that produced this item. + Action type "open_page" - Opens a specific URL from search results. - - `agent_name: String` + - `type: :open_page` - The canonical name of the agent that produced this item. + The action type. - - `approval_request_id: String` + - `:open_page` - 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. + - `url: String` - - `error: String` + The URL opened by the model. - The error from the tool call, if any. + - `class FindInPage` - - `output: String` + Action type "find_in_page": Searches for a pattern within a loaded page. - The output from the tool call. + - `pattern: String` - - `status: :in_progress | :completed | :incomplete | 2 more` + The pattern or text to search for within the page. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `type: :find_in_page` - - `:in_progress` + The action type. - - `:completed` + - `:find_in_page` - - `:incomplete` + - `url: String` - - `:calling` + The URL of the page searched for the pattern. - - `:failed` + - `status: :in_progress | :searching | :completed | :failed` - - `class McpListTools` + The status of the web search tool call. - A list of tools available on an MCP server. + - `:in_progress` - - `id: String` + - `:searching` - The unique ID of the list. + - `:completed` - - `server_label: String` + - `:failed` - The label of the MCP server. + - `type: :web_search_call` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + The type of the web search tool call. Always `web_search_call`. - The tools available on the server. + - `:web_search_call` - - `input_schema: untyped` + - `agent: Agent{ agent_name}` - The JSON schema describing the tool's input. + The agent that produced this item. - - `name: String` + - `agent_name: String` - The name of the tool. + The canonical name of the agent that produced this item. - - `annotations: untyped` + - `class BetaResponseFunctionToolCall` - Additional annotations about the tool. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `description: String` + - `arguments: String` - The description of the tool. + A JSON string of the arguments to pass to the function. - - `type: :mcp_list_tools` + - `call_id: String` - The type of the item. Always `mcp_list_tools`. + The unique ID of the function tool call generated by the model. - - `:mcp_list_tools` + - `name: String` - - `agent: Agent{ agent_name}` + The name of the function to run. - The agent that produced this item. + - `type: :function_call` - - `agent_name: String` + The type of the function tool call. Always `function_call`. - The canonical name of the agent that produced this item. + - `:function_call` - - `error: String` + - `id: String` - Error message if the server could not list tools. + The unique ID of the function tool call. - - `class McpApprovalRequest` + - `agent: Agent{ agent_name}` - A request for human approval of a tool invocation. + The agent that produced this item. - - `id: String` + - `agent_name: String` - The unique ID of the approval request. + The canonical name of the agent that produced this item. - - `arguments: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A JSON string of arguments for the tool. + The execution context that produced this tool call. - - `name: String` + - `class Direct` - The name of the tool to run. + - `type: :direct` - - `server_label: String` + - `:direct` - The label of the MCP server making the request. + - `class Program` - - `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: Agent{ agent_name}` + - `:program` - The agent that produced this item. + - `namespace: String` - - `agent_name: String` + The namespace of the function to run. - The canonical name of the agent that produced this item. + - `status: :in_progress | :completed | :incomplete` - - `class McpApprovalResponse` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A response to an MCP approval request. + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of the approval response + - `:incomplete` - - `approval_request_id: String` + - `class FunctionCallOutput` - The ID of the approval request being answered. + The output of a function tool call. - - `approve: bool` + - `call_id: String` - Whether the request was approved. + The unique ID of the function tool call generated by the model. - - `type: :mcp_approval_response` + - `output: String | BetaResponseFunctionCallOutputItemList` - The type of the item. Always `mcp_approval_response`. + Text, image, or file output of the function tool call. - - `:mcp_approval_response` + - `String = String` - - `agent: Agent{ agent_name}` + A JSON string of the output of the function tool call. - The agent that produced this item. + - `BetaResponseFunctionCallOutputItemList = Array[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. + - `class BetaResponseInputTextContent` - - `reason: String` + A text input to the model. - Optional reason for the decision. + - `text: String` - - `class BetaResponseCustomToolCall` + The text input to the model. - A call to a custom tool created by the model. + - `type: :input_text` - - `call_id: String` + The type of the input item. Always `input_text`. - An identifier used to map this custom tool call to a tool call output. + - `:input_text` - - `input: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The input for the custom tool call generated by the model. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `name: String` + - `mode: :explicit` - The name of the custom tool being called. + The breakpoint mode. Always `explicit`. - - `type: :custom_tool_call` + - `:explicit` - The type of the custom tool call. Always `custom_tool_call`. + - `class BetaResponseInputImageContent` - - `:custom_tool_call` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `id: String` + - `type: :input_image` - The unique ID of the custom tool call in the OpenAI platform. + The type of the input item. Always `input_image`. - - `agent: Agent{ agent_name}` + - `:input_image` - The agent that produced this item. + - `detail: :low | :high | :auto | :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_: Direct{ type} | Program{ caller_id, type}` + - `:high` - The execution context that produced this tool call. + - `:auto` - - `class Direct` + - `:original` - - `type: :direct` + - `file_id: String` - - `:direct` + The ID of the file to be sent to the model. - - `class Program` + - `image_url: String` - - `caller_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 call ID of the program item that produced this tool call. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `type: :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` - - `namespace: String` + The breakpoint mode. Always `explicit`. - The namespace of the custom tool being called. + - `:explicit` - - `class BetaResponseCustomToolCallOutputItem` + - `class BetaResponseInputFileContent` - The output of a custom tool call from your code, being sent back to the model. + 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`. - - `status: :in_progress | :completed | :incomplete` + - `:input_file` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `detail: :auto | :low | :high` - - `:in_progress` + 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`. - - `:completed` + - `:auto` - - `:incomplete` + - `:low` - - `created_by: String` + - `:high` - The identifier of the actor that created the item. + - `file_data: String` - - `usage: BetaResponseUsage` + The base64-encoded data of the file to be sent to the model. - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + - `file_id: String` - - `input_tokens: Integer` + The ID of the file to be sent to the model. - The number of input tokens. + - `file_url: String` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + The URL of the file to be sent to the model. - A detailed breakdown of the input tokens. + - `filename: String` - - `cache_write_tokens: Integer` + The name of the file to be sent to the model. - The number of input tokens that were written to the cache. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `cached_tokens: Integer` + Marks the exact end of a reusable 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 tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `mode: :explicit` - - `output_tokens: Integer` + The breakpoint mode. Always `explicit`. - The number of output tokens. + - `:explicit` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `type: :function_call_output` - A detailed breakdown of the output tokens. + The type of the function tool call output. Always `function_call_output`. - - `reasoning_tokens: Integer` + - `:function_call_output` - The number of reasoning tokens. + - `id: String` - - `total_tokens: Integer` + The unique ID of the function tool call output. Populated when this item is returned via API. - The total number of tokens used. + - `agent: Agent{ agent_name}` -### Beta Computer Action + The agent that produced this item. -- `BetaComputerAction = Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` + - `agent_name: String` - A click action. + The canonical name of the agent that produced this item. - - `class Click` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A click action. + The execution context that produced this tool call. - - `button: :left | :right | :wheel | 2 more` + - `class Direct` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: :direct` - - `:left` + The caller type. Always `direct`. - - `:right` + - `:direct` - - `:wheel` + - `class Program` - - `:back` + - `caller_id: String` - - `:forward` + The call ID of the program item that produced this tool call. - - `type: :click` + - `type: :program` - Specifies the event type. For a click action, this property is always `click`. + The caller type. Always `program`. - - `:click` + - `:program` - - `x: Integer` + - `status: :in_progress | :completed | :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_: Integer` + - `:in_progress` - The y-coordinate where the click occurred. + - `:completed` - - `keys: Array[String]` + - `:incomplete` - The keys being held while clicking. + - `class AgentMessage` - - `class DoubleClick` + A message routed between agents. - A double click action. + - `author: String` - - `keys: Array[String]` + The sending agent identity. - The keys being held while double-clicking. + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `type: :double_click` + Plaintext, image, or encrypted content sent between agents. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `class BetaResponseInputTextContent` - - `:double_click` + A text input to the model. - - `x: Integer` + - `class BetaResponseInputImageContent` - The x-coordinate where the double click occurred. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `y_: Integer` + - `class EncryptedContent` - The y-coordinate where the double click occurred. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `class Drag` + - `encrypted_content: String` - A drag action. + Opaque encrypted content. - - `path: Array[Path{ x, y_}]` + - `type: :encrypted_content` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The type of the input item. Always `encrypted_content`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `:encrypted_content` - - `x: Integer` + - `recipient: String` - The x-coordinate. + The destination agent identity. - - `y_: Integer` + - `type: :agent_message` - The y-coordinate. + The item type. Always `agent_message`. - - `type: :drag` + - `:agent_message` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: String` - - `:drag` + The unique ID of this agent message item. - - `keys: Array[String]` + - `agent: Agent{ agent_name}` - The keys being held while dragging the mouse. + The agent that produced this item. - - `class Keypress` + - `agent_name: String` - A collection of keypresses the model would like to perform. + The canonical name of the agent that produced this item. - - `keys: Array[String]` + - `class MultiAgentCall` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :keypress` + The multi-agent action that was executed. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `:spawn_agent` - - `:keypress` + - `:interrupt_agent` - - `class Move` + - `:list_agents` - A mouse move action. + - `:send_message` - - `type: :move` + - `:followup_task` - Specifies the event type. For a move action, this property is always set to `move`. + - `:wait_agent` - - `:move` + - `arguments: String` - - `x: Integer` + The action arguments as a JSON string. - The x-coordinate to move to. + - `call_id: String` - - `y_: Integer` + The unique ID linking this call to its output. - The y-coordinate to move to. + - `type: :multi_agent_call` - - `keys: Array[String]` + The item type. Always `multi_agent_call`. - The keys being held while moving the mouse. + - `:multi_agent_call` - - `class Screenshot` + - `id: String` - A screenshot action. + The unique ID of this multi-agent call. - - `type: :screenshot` + - `agent: Agent{ agent_name}` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The agent that produced this item. - - `:screenshot` + - `agent_name: String` - - `class Scroll` + The canonical name of the agent that produced this item. - A scroll action. + - `class MultiAgentCallOutput` - - `scroll_x: Integer` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The horizontal scroll distance. + The multi-agent action that produced this result. - - `scroll_y: Integer` + - `:spawn_agent` - The vertical scroll distance. + - `:interrupt_agent` - - `type: :scroll` + - `:list_agents` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `:send_message` - - `:scroll` + - `:followup_task` - - `x: Integer` + - `:wait_agent` - The x-coordinate where the scroll occurred. + - `call_id: String` - - `y_: Integer` + The unique ID of the multi-agent call. - The y-coordinate where the scroll occurred. + - `output: Array[Output{ text, type, annotations}]` - - `keys: Array[String]` + Text output returned by the multi-agent action. - The keys being held while scrolling. + - `text: String` - - `class Type` + The text content. - An action to type in text. + - `type: :output_text` - - `text: String` + The content type. Always `output_text`. - The text to type. + - `:output_text` - - `type: :type` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - Specifies the event type. For a type action, this property is always set to `type`. + Citations associated with the text content. - - `:type` + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `class Wait` + - `file_id: String` - A wait action. + The ID of the file. - - `type: :wait` + - `filename: String` - Specifies the event type. For a wait action, this property is always set to `wait`. + The filename of the file cited. - - `:wait` + - `index: Integer` -### Beta Computer Action List + The index of the file in the list of files. -- `BetaComputerActionList = Array[BetaComputerAction]` + - `type: :file_citation` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The citation type. Always `file_citation`. - - `class Click` + - `:file_citation` - A click action. + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `button: :left | :right | :wheel | 2 more` + - `end_index: Integer` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The index of the last character of the citation in the message. - - `:left` + - `start_index: Integer` - - `:right` + The index of the first character of the citation in the message. - - `:wheel` + - `title: String` - - `:back` + The title of the cited resource. - - `:forward` + - `type: :url_citation` - - `type: :click` + The citation type. Always `url_citation`. - Specifies the event type. For a click action, this property is always `click`. + - `:url_citation` - - `:click` + - `url: String` - - `x: Integer` + The URL of the cited resource. - The x-coordinate where the click occurred. + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `y_: Integer` + - `container_id: String` - The y-coordinate where the click occurred. + The ID of the container. - - `keys: Array[String]` + - `end_index: Integer` - The keys being held while clicking. + The index of the last character of the citation in the message. - - `class DoubleClick` + - `file_id: String` - A double click action. + The ID of the container file. - - `keys: Array[String]` + - `filename: String` - The keys being held while double-clicking. + The filename of the container file cited. - - `type: :double_click` + - `start_index: Integer` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The index of the first character of the citation in the message. - - `:double_click` + - `type: :container_file_citation` - - `x: Integer` + The citation type. Always `container_file_citation`. - The x-coordinate where the double click occurred. + - `:container_file_citation` - - `y_: Integer` + - `type: :multi_agent_call_output` - The y-coordinate where the double click occurred. + The item type. Always `multi_agent_call_output`. - - `class Drag` + - `:multi_agent_call_output` - A drag action. + - `id: String` - - `path: Array[Path{ x, y_}]` + The unique ID of this multi-agent call output. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `agent: Agent{ agent_name}` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The agent that produced this item. - - `x: Integer` + - `agent_name: String` - The x-coordinate. + The canonical name of the agent that produced this item. - - `y_: Integer` + - `class ToolSearchCall` - The y-coordinate. + - `arguments: untyped` - - `type: :drag` + The arguments supplied to the tool search call. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: :tool_search_call` - - `:drag` + The item type. Always `tool_search_call`. - - `keys: Array[String]` + - `:tool_search_call` - The keys being held while dragging the mouse. + - `id: String` - - `class Keypress` + The unique ID of this tool search call. - A collection of keypresses the model would like to perform. + - `agent: Agent{ agent_name}` - - `keys: Array[String]` + The agent that produced this item. - 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`. + - `call_id: String` - - `:keypress` + The unique ID of the tool search call generated by the model. - - `class Move` + - `execution: :server | :client` - A mouse move action. + Whether tool search was executed by the server or by the client. - - `type: :move` + - `:server` - Specifies the event type. For a move action, this property is always set to `move`. + - `:client` - - `:move` + - `status: :in_progress | :completed | :incomplete` - - `x: Integer` + The status of the tool search call. - The x-coordinate to move to. + - `:in_progress` - - `y_: Integer` + - `:completed` - The y-coordinate to move to. + - `:incomplete` - - `keys: Array[String]` + - `class BetaResponseToolSearchOutputItemParam` - The keys being held while moving the mouse. + - `tools: Array[BetaTool]` - - `class Screenshot` + The loaded tool definitions returned by the tool search output. - A screenshot action. + - `class BetaFunctionTool` - - `type: :screenshot` + 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 screenshot action, this property is always set to `screenshot`. + - `name: String` - - `:screenshot` + The name of the function to call. - - `class Scroll` + - `parameters: Hash[Symbol, untyped]` - A scroll action. + A JSON schema object describing the parameters of the function. - - `scroll_x: Integer` + - `strict: bool` - The horizontal scroll distance. + Whether strict parameter validation is enforced for this function tool. - - `scroll_y: Integer` + - `type: :function` - The vertical scroll distance. + The type of the function tool. Always `function`. - - `type: :scroll` + - `:function` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:scroll` + The tool invocation context(s). - - `x: Integer` + - `:direct` - The x-coordinate where the scroll occurred. + - `:programmatic` - - `y_: Integer` + - `defer_loading: bool` - The y-coordinate where the scroll occurred. + Whether this function is deferred and loaded via tool search. - - `keys: Array[String]` + - `description: String` - The keys being held while scrolling. + A description of the function. Used by the model to determine whether or not to call the function. - - `class Type` + - `output_schema: Hash[Symbol, untyped]` - An action to type in text. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `text: String` + - `class BetaFileSearchTool` - The text to 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). - - `type: :type` + - `type: :file_search` - Specifies the event type. For a type action, this property is always set to `type`. + The type of the file search tool. Always `file_search`. - - `:type` + - `:file_search` - - `class Wait` + - `vector_store_ids: Array[String]` - A wait action. + The IDs of the vector stores to search. - - `type: :wait` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - Specifies the event type. For a wait action, this property is always set to `wait`. + A filter to apply. - - `:wait` + - `class ComparisonFilter` -### Beta Computer Tool + A filter used to compare a specified attribute key to a given value using a defined comparison operation. -- `class BetaComputerTool` + - `key: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The key to compare against the value. - - `type: :computer` + - `type: :eq | :ne | :gt | 5 more` - The type of the computer tool. Always `computer`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:computer` + - `eq`: equals + - `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 Computer Use Preview Tool + - `:eq` -- `class BetaComputerUsePreviewTool` + - `:ne` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:gt` - - `display_height: Integer` + - `:gte` - The height of the computer display. + - `:lt` - - `display_width: Integer` + - `:lte` - The width of the computer display. + - `:in` - - `environment: :windows | :mac | :linux | 2 more` + - `:nin` - The type of computer environment to control. + - `value: String | Float | bool | Array[String | Float]` - - `:windows` + The value to compare against the attribute key; supports string, number, or boolean types. - - `:mac` + - `String = String` - - `:linux` + - `Float = Float` - - `:ubuntu` + - `UnionMember2 = bool` - - `:browser` + - `UnionMember3 = Array[String | Float]` - - `type: :computer_use_preview` + - `String = String` - The type of the computer use tool. Always `computer_use_preview`. + - `Float = Float` - - `:computer_use_preview` + - `class CompoundFilter` -### Beta Container Auto + Combine multiple filters using `and` or `or`. -- `class BetaContainerAuto` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `type: :container_auto` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Automatically creates a container for this request + - `class ComparisonFilter` - - `:container_auto` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `file_ids: Array[String]` + - `key: String` - An optional list of uploaded files to make available to your code. + The key to compare against the value. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `type: :eq | :ne | :gt | 5 more` - The memory limit for the container. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:"1g"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `:"4g"` + - `:eq` - - `:"16g"` + - `:ne` - - `:"64g"` + - `:gt` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:gte` - Network access policy for the container. + - `:lt` - - `class BetaContainerNetworkPolicyDisabled` + - `:lte` - - `type: :disabled` + - `:in` - Disable outbound network access. Always `disabled`. + - `:nin` - - `:disabled` + - `value: String | Float | bool | Array[String | Float]` - - `class BetaContainerNetworkPolicyAllowlist` + The value to compare against the attribute key; supports string, number, or boolean types. - - `allowed_domains: Array[String]` + - `String = String` - A list of allowed domains when type is `allowlist`. + - `Float = Float` - - `type: :allowlist` + - `UnionMember2 = bool` - Allow outbound network access only to specified domains. Always `allowlist`. + - `UnionMember3 = Array[String | Float]` - - `:allowlist` + - `String = String` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `Float = Float` - Optional domain-scoped secrets for allowlisted domains. + - `UnionMember1 = untyped` - - `domain: String` + - `type: :and | :or` - The domain associated with the secret. + Type of operation: `and` or `or`. - - `name: String` + - `:and` - The name of the secret to inject for the domain. + - `:or` - - `value: String` + - `max_num_results: Integer` - The secret value to inject for the domain. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - An optional list of skills referenced by id or inline data. + Ranking options for search. - - `class BetaSkillReference` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `skill_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 referenced skill. + - `embedding_weight: Float` - - `type: :skill_reference` + The weight of the embedding in the reciprocal ranking fusion. - References a skill created with the /v1/skills endpoint. + - `text_weight: Float` - - `:skill_reference` + The weight of the text in the reciprocal ranking fusion. - - `version: String` + - `ranker: :auto | :"default-2024-11-15"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The ranker to use for the file search. - - `class BetaInlineSkill` + - `:auto` - - `description: String` + - `:"default-2024-11-15"` - The description of the skill. + - `score_threshold: Float` - - `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 skill. + - `class BetaComputerTool` - - `source: BetaInlineSkillSource` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Inline skill payload + - `type: :computer` - - `data: String` + The type of the computer tool. Always `computer`. - Base64-encoded skill zip bundle. + - `:computer` - - `media_type: :"application/zip"` + - `class BetaComputerUsePreviewTool` - The media type of the inline skill payload. Must be `application/zip`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:"application/zip"` + - `display_height: Integer` - - `type: :base64` + The height of the computer display. - The type of the inline skill source. Must be `base64`. + - `display_width: Integer` - - `:base64` + The width of the computer display. - - `type: :inline` + - `environment: :windows | :mac | :linux | 2 more` - Defines an inline skill for this request. + The type of computer environment to control. - - `:inline` + - `:windows` -### Beta Container Network Policy Allowlist + - `:mac` -- `class BetaContainerNetworkPolicyAllowlist` + - `:linux` - - `allowed_domains: Array[String]` + - `:ubuntu` - A list of allowed domains when type is `allowlist`. + - `:browser` - - `type: :allowlist` + - `type: :computer_use_preview` - Allow outbound network access only to specified domains. Always `allowlist`. + The type of the computer use tool. Always `computer_use_preview`. - - `:allowlist` + - `:computer_use_preview` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `class BetaWebSearchTool` - Optional domain-scoped secrets for allowlisted domains. + 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). - - `domain: String` + - `type: :web_search | :web_search_2025_08_26` - The domain associated with the secret. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `name: String` + - `:web_search` - The name of the secret to inject for the domain. + - `:web_search_2025_08_26` - - `value: String` + - `filters: Filters{ allowed_domains}` - The secret value to inject for the domain. + Filters for the search. -### Beta Container Network Policy Disabled + - `allowed_domains: Array[String]` -- `class BetaContainerNetworkPolicyDisabled` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `type: :disabled` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Disable outbound network access. Always `disabled`. + - `search_context_size: :low | :medium | :high` - - `:disabled` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. -### Beta Container Network Policy Domain Secret + - `:low` -- `class BetaContainerNetworkPolicyDomainSecret` + - `:medium` - - `domain: String` + - `:high` - The domain associated with the secret. + - `user_location: UserLocation{ city, country, region, 2 more}` - - `name: String` + The approximate location of the user. - The name of the secret to inject for the domain. + - `city: String` - - `value: String` + Free text input for the city of the user, e.g. `San Francisco`. - The secret value to inject for the domain. + - `country: String` -### Beta Container Reference + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. -- `class BetaContainerReference` + - `region: String` - - `container_id: String` + Free text input for the region of the user, e.g. `California`. - The ID of the referenced container. + - `timezone: String` - - `type: :container_reference` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - References a container created with the /v1/containers endpoint + - `type: :approximate` - - `:container_reference` + The type of location approximation. Always `approximate`. -### Beta Custom Tool + - `:approximate` -- `class BetaCustomTool` + - `class Mcp` - 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) + 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). - - `name: String` + - `server_label: String` - The name of the custom tool, used to identify it in tool calls. + A label for this MCP server, used to identify it in tool calls. - - `type: :custom` + - `type: :mcp` - The type of the custom tool. Always `custom`. + The type of the MCP tool. Always `mcp`. - - `:custom` + - `:mcp` - `allowed_callers: Array[:direct | :programmatic]` @@ -50749,382 +61107,394 @@ puts(beta_compacted_response) - `:programmatic` - - `defer_loading: bool` - - Whether this tool should be deferred and discovered via tool search. - - - `description: String` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - Optional description of the custom tool, used to provide more context. + List of allowed tool names or a filter object. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `McpAllowedTools = Array[String]` - The input format for the custom tool. Default is unconstrained text. + A string array of allowed tool names - - `class Text` + - `class McpToolFilter` - Unconstrained free-form text. + A filter object to specify which tools are allowed. - - `type: :text` + - `read_only: bool` - Unconstrained text format. Always `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. - - `:text` + - `tool_names: Array[String]` - - `class Grammar` + List of allowed tool names. - A grammar defined by the user. + - `authorization: String` - - `definition: 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 grammar definition. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `syntax: :lark | :regex` + 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 syntax of the grammar definition. One of `lark` or `regex`. + Currently supported `connector_id` values are: - - `:lark` + - 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` - - `:regex` + - `:connector_dropbox` - - `type: :grammar` + - `:connector_gmail` - Grammar format. Always `grammar`. + - `:connector_googlecalendar` - - `:grammar` + - `:connector_googledrive` -### Beta Easy Input Message + - `:connector_microsoftteams` -- `class BetaEasyInputMessage` + - `:connector_outlookcalendar` - 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_outlookemail` - - `content: String | BetaResponseInputMessageContentList` + - `:connector_sharepoint` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `defer_loading: bool` - - `String = String` + Whether this MCP tool is deferred and discovered via tool search. - A text input to the model. + - `headers: Hash[Symbol, String]` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - A list of one or many input items to the model, containing different content - types. + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `class BetaResponseInputText` + Specify which of the MCP server's tools require approval. - A text input to the model. + - `class McpToolApprovalFilter` - - `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 input to the model. + - `always: Always{ read_only, tool_names}` - - `type: :input_text` + A filter object to specify which tools are allowed. - The type of the input item. Always `input_text`. + - `read_only: bool` - - `:input_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. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `tool_names: Array[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. + List of allowed tool names. - - `mode: :explicit` + - `never: Never{ read_only, tool_names}` - The breakpoint mode. Always `explicit`. + A filter object to specify which tools are allowed. - - `:explicit` + - `read_only: bool` - - `class BetaResponseInputImage` + Indicates whether or not a tool modifies data or is read-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 image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `tool_names: Array[String]` - - `detail: :low | :high | :auto | :original` + List of allowed tool names. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `McpToolApprovalSetting = :always | :never` - - `:low` + 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` - - `:auto` + - `:never` - - `:original` + - `server_description: String` - - `type: :input_image` + Optional description of the MCP server, used to provide more context. - The type of the input item. Always `input_image`. + - `server_url: String` - - `:input_image` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `file_id: String` + - `tunnel_id: String` - The ID of the file to be sent to the model. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `image_url: String` + - `class CodeInterpreter` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A tool that runs Python code to help generate a response to a prompt. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + 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. - - `mode: :explicit` + - `String = String` - The breakpoint mode. Always `explicit`. + The container ID. - - `:explicit` + - `class CodeInterpreterToolAuto` - - `class BetaResponseInputFile` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A file input to the model. + - `type: :auto` - - `type: :input_file` + Always `auto`. - The type of the input item. Always `input_file`. + - `:auto` - - `:input_file` + - `file_ids: Array[String]` - - `detail: :auto | :low | :high` + An optional list of uploaded files to make available to your code. - 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`. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:auto` + The memory limit for the code interpreter container. - - `:low` + - `:"1g"` - - `:high` + - `:"4g"` - - `file_data: String` + - `:"16g"` - The content of the file to be sent to the model. + - `:"64g"` - - `file_id: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The ID of the file to be sent to the model. + Network access policy for the container. - - `file_url: String` + - `class BetaContainerNetworkPolicyDisabled` - The URL of the file to be sent to the model. + - `type: :disabled` - - `filename: String` + Disable outbound network access. Always `disabled`. - The name of the file to be sent to the model. + - `:disabled` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class 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. + - `allowed_domains: Array[String]` - - `mode: :explicit` + A list of allowed domains when type is `allowlist`. - The breakpoint mode. Always `explicit`. + - `type: :allowlist` - - `:explicit` + Allow outbound network access only to specified domains. Always `allowlist`. - - `role: :user | :assistant | :system | :developer` + - `:allowlist` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `:user` + Optional domain-scoped secrets for allowlisted domains. - - `:assistant` + - `domain: String` - - `:system` + The domain associated with the secret. - - `:developer` + - `name: String` - - `phase: :commentary` + The name of the secret to inject for the domain. - 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. + - `value: String` - - `:commentary` + The secret value to inject for the domain. - - `type: :message` + - `type: :code_interpreter` - The type of the message input. Always `message`. + The type of the code interpreter tool. Always `code_interpreter`. - - `:message` + - `:code_interpreter` -### Beta File Search Tool + - `allowed_callers: Array[:direct | :programmatic]` -- `class BetaFileSearchTool` + The tool invocation context(s). - 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). + - `:direct` - - `type: :file_search` + - `:programmatic` - The type of the file search tool. Always `file_search`. + - `class ProgrammaticToolCalling` - - `:file_search` + - `type: :programmatic_tool_calling` - - `vector_store_ids: Array[String]` + The type of the tool. Always `programmatic_tool_calling`. - The IDs of the vector stores to search. + - `:programmatic_tool_calling` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `class ImageGeneration` - A filter to apply. + A tool that generates images using the GPT image models. - - `class ComparisonFilter` + - `type: :image_generation` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The type of the image generation tool. Always `image_generation`. - - `key: String` + - `:image_generation` - The key to compare against the value. + - `action: :generate | :edit | :auto` - - `type: :eq | :ne | :gt | 5 more` + Whether to generate a new image or edit an existing image. Default: `auto`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `:generate` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `:edit` - - `:eq` + - `:auto` - - `:ne` + - `background: :transparent | :opaque | :auto` - - `:gt` + 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. - - `:gte` + `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. - - `:lt` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `:lte` + - `:transparent` - - `:in` + - `:opaque` - - `:nin` + - `:auto` - - `value: String | Float | bool | Array[untyped]` + - `input_fidelity: :high | :low` - The value to compare against the attribute key; supports string, number, or boolean types. + 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`. - - `String = String` + - `:high` - - `Float = Float` + - `:low` - - `UnionMember2 = bool` + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `UnionMember3 = Array[untyped]` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `class CompoundFilter` + - `file_id: String` - Combine multiple filters using `and` or `or`. + File ID for the mask image. - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + - `image_url: String` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Base64-encoded mask image. - - `class ComparisonFilter` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The image generation model to use. Default: `gpt-image-1`. - - `key: String` + - `String = String` - The key to compare against the value. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `type: :eq | :ne | :gt | 5 more` + The image generation model to use. Default: `gpt-image-1`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `:"gpt-image-1"` - - `eq`: equals - - `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-image-1-mini"` - - `:eq` + - `:"gpt-image-2"` - - `:ne` + - `:"gpt-image-2-2026-04-21"` - - `:gt` + - `:"gpt-image-1.5"` - - `:gte` + - `:"chatgpt-image-latest"` - - `:lt` + - `moderation: :auto | :low` - - `:lte` + Moderation level for the generated image. Default: `auto`. - - `:in` + - `:auto` - - `:nin` + - `:low` - - `value: String | Float | bool | Array[untyped]` + - `output_compression: Integer` - The value to compare against the attribute key; supports string, number, or boolean types. + Compression level for the output image. Default: 100. - - `String = String` + - `output_format: :png | :webp | :jpeg` - - `Float = Float` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `UnionMember2 = bool` + - `:png` - - `UnionMember3 = Array[untyped]` + - `:webp` - - `UnionMember1 = untyped` + - `:jpeg` - - `type: :and | :or` + - `partial_images: Integer` - Type of operation: `and` or `or`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `:and` + - `quality: :low | :medium | :high | :auto` - - `:or` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `max_num_results: Integer` + - `:low` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `:medium` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `:high` - Ranking options for search. + - `:auto` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search 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`. - - `embedding_weight: Float` + - `String = String` - The weight of the embedding in the reciprocal ranking fusion. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `text_weight: Float` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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 weight of the text in the reciprocal ranking fusion. + - `:"1024x1024"` - - `ranker: :auto | :"default-2024-11-15"` + - `:"1024x1536"` - The ranker to use for the file search. + - `:"1536x1024"` - `:auto` - - `:"default-2024-11-15"` + - `class LocalShell` - - `score_threshold: Float` + A tool that allows the model to execute shell commands in a local environment. - 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: :local_shell` -### Beta Function Shell Tool + The type of the local shell tool. Always `local_shell`. -- `class BetaFunctionShellTool` + - `:local_shell` + + - `class BetaFunctionShellTool` A tool that allows the model to execute shell commands. @@ -51160,53 +61530,21 @@ puts(beta_compacted_response) The memory limit for the container. - - `:"1g"` - - - `:"4g"` - - - `:"16g"` - - - `:"64g"` - - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class BetaContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class BetaContainerNetworkPolicyAllowlist` - - - `allowed_domains: Array[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: Array[BetaContainerNetworkPolicyDomainSecret]` + - `:"1g"` - Optional domain-scoped secrets for allowlisted domains. + - `:"4g"` - - `domain: String` + - `:"16g"` - The domain associated with the secret. + - `:"64g"` - - `name: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The name of the secret to inject for the domain. + Network access policy for the container. - - `value: String` + - `class BetaContainerNetworkPolicyDisabled` - The secret value to inject for the domain. + - `class BetaContainerNetworkPolicyAllowlist` - `skills: Array[BetaSkillReference | BetaInlineSkill]` @@ -51300,29 +61638,19 @@ puts(beta_compacted_response) - `:container_reference` -### Beta Function Tool - -- `class BetaFunctionTool` + - `class BetaCustomTool` - 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 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 function to call. - - - `parameters: Hash[Symbol, untyped]` - - A JSON schema object describing the parameters of the function. - - - `strict: bool` - - Whether strict parameter validation is enforced for this function tool. + The name of the custom tool, used to identify it in tool calls. - - `type: :function` + - `type: :custom` - The type of the function tool. Always `function`. + The type of the custom tool. Always `custom`. - - `:function` + - `:custom` - `allowed_callers: Array[:direct | :programmatic]` @@ -51334,121 +61662,49 @@ puts(beta_compacted_response) - `defer_loading: bool` - Whether this function is deferred and loaded via tool search. - - - `description: String` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: Hash[Symbol, untyped]` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - -### Beta Inline Skill - -- `class BetaInlineSkill` + Whether this tool should be deferred and discovered via tool search. - `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` - -### Beta Inline Skill Source - -- `class 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` - -### Beta Local Environment - -- `class BetaLocalEnvironment` - - - `type: :local` - - Use a local computer environment. + Optional description of the custom tool, used to provide more context. - - `:local` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `skills: Array[BetaLocalSkill]` + The input format for the custom tool. Default is unconstrained text. - An optional list of skills. + - `class Text` - - `description: String` + Unconstrained free-form text. - The description of the skill. + - `type: :text` - - `name: String` + Unconstrained text format. Always `text`. - The name of the skill. + - `:text` - - `path: String` + - `class Grammar` - The path to the directory containing the skill. + A grammar defined by the user. -### Beta Local Skill + - `definition: String` -- `class BetaLocalSkill` + The grammar definition. - - `description: String` + - `syntax: :lark | :regex` - The description of the skill. + The syntax of the grammar definition. One of `lark` or `regex`. - - `name: String` + - `:lark` - The name of the skill. + - `:regex` - - `path: String` + - `type: :grammar` - The path to the directory containing the skill. + Grammar format. Always `grammar`. -### Beta Namespace Tool + - `:grammar` -- `class BetaNamespaceTool` + - `class BetaNamespaceTool` Groups function/custom tools under a shared namespace. @@ -51500,345 +61756,330 @@ puts(beta_compacted_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) - - `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`. + - `type: :namespace` - - `:custom` + The type of the tool. Always `namespace`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:namespace` - The tool invocation context(s). + - `class BetaToolSearchTool` - - `:direct` + Hosted or BYOT tool search configuration for deferred tools. - - `:programmatic` + - `type: :tool_search` - - `defer_loading: bool` + The type of the tool. Always `tool_search`. - Whether this tool should be deferred and discovered via tool search. + - `:tool_search` - `description: String` - Optional description of the custom tool, used to provide more context. + Description shown to the model for a client-executed tool search tool. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `execution: :server | :client` - The input format for the custom tool. Default is unconstrained text. + Whether tool search is executed by the server or by the client. - - `class Text` + - `:server` - Unconstrained free-form text. + - `:client` - - `type: :text` + - `parameters: untyped` - Unconstrained text format. Always `text`. + Parameter schema for a client-executed tool search tool. - - `:text` + - `class BetaWebSearchPreviewTool` - - `class Grammar` + 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 grammar defined by the user. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `definition: String` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The grammar definition. + - `:web_search_preview` - - `syntax: :lark | :regex` + - `:web_search_preview_2025_03_11` - The syntax of the grammar definition. One of `lark` or `regex`. + - `search_content_types: Array[:text | :image]` - - `:lark` + - `:text` - - `:regex` + - `:image` - - `type: :grammar` + - `search_context_size: :low | :medium | :high` - Grammar format. Always `grammar`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `:grammar` + - `:low` - - `type: :namespace` + - `:medium` - The type of the tool. Always `namespace`. + - `:high` - - `:namespace` + - `user_location: UserLocation{ type, city, country, 2 more}` -### Beta Response + The user's location. -- `class BetaResponse` + - `type: :approximate` - - `id: String` + The type of location approximation. Always `approximate`. - Unique identifier for this Response. + - `:approximate` - - `created_at: Float` + - `city: String` - Unix timestamp (in seconds) of when this Response was created. + Free text input for the city of the user, e.g. `San Francisco`. - - `error: BetaResponseError` + - `country: String` - An error object returned when the model fails to generate a Response. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `region: String` - The error code for the response. + Free text input for the region of the user, e.g. `California`. - - `:server_error` + - `timezone: String` - - `:rate_limit_exceeded` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:invalid_prompt` + - `class BetaApplyPatchTool` - - `:bio_policy` + Allows the assistant to create, delete, or update files using unified diffs. - - `:vector_store_timeout` + - `type: :apply_patch` - - `:invalid_image` + The type of the tool. Always `apply_patch`. - - `:invalid_image_format` + - `:apply_patch` - - `:invalid_base64_image` + - `allowed_callers: Array[:direct | :programmatic]` - - `:invalid_image_url` + The tool invocation context(s). - - `:image_too_large` + - `:direct` - - `:image_too_small` + - `:programmatic` - - `:image_parse_error` + - `type: :tool_search_output` - - `:image_content_policy_violation` + The item type. Always `tool_search_output`. - - `:invalid_image_mode` + - `:tool_search_output` - - `:image_file_too_large` + - `id: String` - - `:unsupported_image_media_type` + The unique ID of this tool search output. - - `:empty_image_file` + - `agent: Agent{ agent_name}` - - `:failed_to_download_image` + The agent that produced this item. - - `:image_file_not_found` + - `agent_name: String` - - `message: String` + The canonical name of the agent that produced this item. - A human-readable description of the error. + - `call_id: String` - - `incomplete_details: IncompleteDetails{ reason}` + The unique ID of the tool search call generated by the model. - Details about why the response is incomplete. + - `execution: :server | :client` - - `reason: :max_output_tokens | :content_filter` + Whether tool search was executed by the server or by the client. - The reason why the response is incomplete. + - `:server` - - `:max_output_tokens` + - `:client` - - `:content_filter` + - `status: :in_progress | :completed | :incomplete` - - `instructions: String | Array[BetaResponseInputItem]` + The status of the tool search output. - 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 = String` + - `:incomplete` - A text input to the model, equivalent to a text input with the - `developer` role. + - `class AdditionalTools` - - `InputItemList = Array[BetaResponseInputItem]` + - `role: :developer` - A list of one or many input items to the model, containing - different content types. + The role that provided the additional tools. Only `developer` is supported. - - `class BetaEasyInputMessage` + - `:developer` - 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. + - `tools: Array[BetaTool]` - - `content: String | BetaResponseInputMessageContentList` + A list of additional tools made available at this item. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `class BetaFunctionTool` - - `String = 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). - A text input to the model. + - `class BetaFileSearchTool` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + 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 list of one or many input items to the model, containing different content - types. + - `class BetaComputerTool` - - `class BetaResponseInputText` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A text input to the model. + - `class BetaComputerUsePreviewTool` - - `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. + - `class BetaWebSearchTool` - - `type: :input_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). - The type of the input item. Always `input_text`. + - `class Mcp` - - `:input_text` + 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). - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class CodeInterpreter` - Marks the exact end of a reusable 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 that runs Python code to help generate a response to a prompt. - - `mode: :explicit` + - `class ProgrammaticToolCalling` - The breakpoint mode. Always `explicit`. + - `class ImageGeneration` - - `:explicit` + A tool that generates images using the GPT image models. - - `class BetaResponseInputImage` + - `class LocalShell` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A tool that allows the model to execute shell commands in a local environment. - - `detail: :low | :high | :auto | :original` + - `class BetaFunctionShellTool` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A tool that allows the model to execute shell commands. - - `:low` + - `class BetaCustomTool` - - `:high` + 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) - - `:auto` + - `class BetaNamespaceTool` - - `:original` + Groups function/custom tools under a shared namespace. - - `type: :input_image` + - `class BetaToolSearchTool` - The type of the input item. Always `input_image`. + Hosted or BYOT tool search configuration for deferred tools. - - `:input_image` + - `class BetaWebSearchPreviewTool` - - `file_id: String` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The ID of the file to be sent to the model. + - `class BetaApplyPatchTool` - - `image_url: String` + Allows the assistant to create, delete, or update files using unified diffs. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: :additional_tools` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The item type. Always `additional_tools`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:additional_tools` - - `mode: :explicit` + - `id: String` - The breakpoint mode. Always `explicit`. + The unique ID of this additional tools item. - - `:explicit` + - `agent: Agent{ agent_name}` - - `class BetaResponseInputFile` + The agent that produced this item. - A file input to the model. + - `agent_name: String` - - `type: :input_file` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_file`. + - `class BetaResponseReasoningItem` - - `:input_file` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `detail: :auto | :low | :high` + - `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 identifier of the reasoning content. - - `:auto` + - `summary: Array[Summary{ text, type}]` - - `:low` + Reasoning summary content. - - `:high` + - `text: String` - - `file_data: String` + A summary of the reasoning output from the model so far. - The content of the file to be sent to the model. + - `type: :summary_text` - - `file_id: String` + The type of the object. Always `summary_text`. - The ID of the file to be sent to the model. + - `:summary_text` - - `file_url: String` + - `type: :reasoning` - The URL of the file to be sent to the model. + The type of the object. Always `reasoning`. - - `filename: String` + - `:reasoning` - The name of the file to be sent to the model. + - `agent: Agent{ agent_name}` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `agent_name: String` - - `mode: :explicit` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `content: Array[Content{ text, type}]` - - `:explicit` + Reasoning text content. - - `role: :user | :assistant | :system | :developer` + - `text: String` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The reasoning text from the model. - - `:user` + - `type: :reasoning_text` - - `:assistant` + The type of the reasoning text. Always `reasoning_text`. - - `:system` + - `:reasoning_text` - - `:developer` + - `encrypted_content: String` - - `phase: :commentary` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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. + - `status: :in_progress | :completed | :incomplete` - - `:commentary` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: :message` + - `:in_progress` - The type of the message input. Always `message`. + - `:completed` - - `:message` + - `:incomplete` - - `class Message` + - `class BetaResponseCompactionItemParam` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `content: BetaResponseInputMessageContentList` + - `encrypted_content: String` - A list of one or many input items to the model, containing different content - types. + The encrypted content of the compaction summary. - - `role: :user | :system | :developer` + - `type: :compaction` - The role of the message input. One of `user`, `system`, or `developer`. + The type of the item. Always `compaction`. - - `:user` + - `:compaction` - - `:system` + - `id: String` - - `:developer` + The ID of the compaction item. - `agent: Agent{ agent_name}` @@ -51848,201 +62089,204 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `class ImageGenerationCall` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + An image generation request made by the model. - - `:in_progress` + - `id: String` - - `:completed` + The unique ID of the image generation call. - - `:incomplete` + - `result: String` - - `type: :message` + The generated image encoded in base64. - The type of the message input. Always set to `message`. + - `status: :in_progress | :completed | :generating | :failed` - - `:message` + The status of the image generation call. - - `class BetaResponseOutputMessage` + - `:in_progress` - An output message from the model. + - `:completed` - - `id: String` + - `:generating` - The unique ID of the output message. + - `:failed` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `type: :image_generation_call` - The content of the output message. + The type of the image generation call. Always `image_generation_call`. - - `class BetaResponseOutputText` + - `:image_generation_call` - A text output from the model. + - `agent: Agent{ agent_name}` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The agent that produced this item. - The annotations of the text output. + - `agent_name: String` - - `class FileCitation` + The canonical name of the agent that produced this item. - A citation to a file. + - `class BetaResponseCodeInterpreterToolCall` - - `file_id: String` + A tool call to run code. - The ID of the file. + - `id: String` - - `filename: String` + The unique ID of the code interpreter tool call. - The filename of the file cited. + - `code: String` - - `index: Integer` + The code to run, or null if not available. - The index of the file in the list of files. + - `container_id: String` - - `type: :file_citation` + The ID of the container used to run the code. - The type of the file citation. Always `file_citation`. + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `:file_citation` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `class URLCitation` + - `class Logs` - A citation for a web resource used to generate a model response. + The logs output from the code interpreter. - - `end_index: Integer` + - `logs: String` - The index of the last character of the URL citation in the message. + The logs output from the code interpreter. - - `start_index: Integer` + - `type: :logs` - The index of the first character of the URL citation in the message. + The type of the output. Always `logs`. - - `title: String` + - `:logs` - The title of the web resource. + - `class Image` - - `type: :url_citation` + The image output from the code interpreter. - The type of the URL citation. Always `url_citation`. + - `type: :image` - - `:url_citation` + The type of the output. Always `image`. + + - `:image` - `url: String` - The URL of the web resource. + The URL of the image output from the code interpreter. - - `class ContainerFileCitation` + - `status: :in_progress | :completed | :incomplete | 2 more` - A citation for a container file used to generate a model response. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `container_id: String` + - `:in_progress` - The ID of the container file. + - `:completed` - - `end_index: Integer` + - `:incomplete` - The index of the last character of the container file citation in the message. + - `:interpreting` - - `file_id: String` + - `:failed` - The ID of the file. + - `type: :code_interpreter_call` - - `filename: String` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The filename of the container file cited. + - `:code_interpreter_call` - - `start_index: Integer` + - `agent: Agent{ agent_name}` - The index of the first character of the container file citation in the message. + The agent that produced this item. - - `type: :container_file_citation` + - `agent_name: String` - The type of the container file citation. Always `container_file_citation`. + The canonical name of the agent that produced this item. - - `:container_file_citation` + - `class LocalShellCall` - - `class FilePath` + A tool call to run a command on the local shell. - A path to a file. + - `id: String` - - `file_id: String` + The unique ID of the local shell call. - The ID of the file. + - `action: Action{ command, env, type, 3 more}` - - `index: Integer` + Execute a shell command on the server. - The index of the file in the list of files. + - `command: Array[String]` - - `type: :file_path` + The command to run. - The type of the file path. Always `file_path`. + - `env: Hash[Symbol, String]` - - `:file_path` + Environment variables to set for the command. - - `text: String` + - `type: :exec` - The text output from the model. + The type of the local shell action. Always `exec`. - - `type: :output_text` + - `:exec` - The type of the output text. Always `output_text`. + - `timeout_ms: Integer` - - `:output_text` + Optional timeout in milliseconds for the command. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `user: String` - - `token: String` + Optional user to run the command as. - - `bytes: Array[Integer]` + - `working_directory: String` - - `logprob: Float` + Optional working directory to run the command in. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `call_id: String` - - `token: String` + The unique ID of the local shell tool call generated by the model. - - `bytes: Array[Integer]` + - `status: :in_progress | :completed | :incomplete` - - `logprob: Float` + The status of the local shell call. - - `class BetaResponseOutputRefusal` + - `:in_progress` - A refusal from the model. + - `:completed` - - `refusal: String` + - `:incomplete` - The refusal explanation from the model. + - `type: :local_shell_call` - - `type: :refusal` + The type of the local shell call. Always `local_shell_call`. - The type of the refusal. Always `refusal`. + - `:local_shell_call` - - `:refusal` + - `agent: Agent{ agent_name}` - - `role: :assistant` + The agent that produced this item. - The role of the output message. Always `assistant`. + - `agent_name: String` - - `:assistant` + The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `class LocalShellCallOutput` - 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. - - `:in_progress` + - `id: String` - - `:completed` + The unique ID of the local shell tool call generated by the model. - - `:incomplete` + - `output: String` - - `type: :message` + A JSON string of the output of the local shell tool call. - The type of the output message. Always `message`. + - `type: :local_shell_call_output` - - `:message` + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `:local_shell_call_output` - `agent: Agent{ agent_name}` @@ -52052,47 +62296,49 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `status: :in_progress | :completed | :incomplete` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `:commentary` + - `:in_progress` - - `class BetaResponseFileSearchToolCall` + - `:completed` - 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. + - `:incomplete` - - `id: String` + - `class ShellCall` - The unique ID of the file search tool call. + A tool representing a request to execute one or more shell commands. - - `queries: Array[String]` + - `action: Action{ commands, max_output_length, timeout_ms}` - The queries used to search for files. + The shell commands and limits that describe how to run the tool call. - - `status: :in_progress | :searching | :completed | 2 more` + - `commands: Array[String]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Ordered shell commands for the execution environment to run. - - `:in_progress` + - `max_output_length: Integer` - - `:searching` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `:completed` + - `timeout_ms: Integer` - - `:incomplete` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `:failed` + - `call_id: String` - - `type: :file_search_call` + The unique ID of the shell tool call generated by the model. - The type of the file search tool call. Always `file_search_call`. + - `type: :shell_call` - - `:file_search_call` + The type of the item. Always `shell_call`. + + - `:shell_call` + + - `id: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -52102,382 +62348,401 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The results of the file search tool call. + The execution context that produced this tool call. - - `attributes: Hash[Symbol, String | Float | bool]` + - `class 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. + - `type: :direct` - - `String = String` + The caller type. Always `direct`. - - `Float = Float` + - `:direct` - - `UnionMember2 = bool` + - `class Program` - - `file_id: String` + - `caller_id: String` - The unique ID of the file. + The call ID of the program item that produced this tool call. - - `filename: String` + - `type: :program` - The name of the file. + The caller type. Always `program`. - - `score: Float` + - `:program` - The relevance score of the file - a value between 0 and 1. + - `environment: BetaLocalEnvironment | BetaContainerReference` - - `text: String` + The environment to execute the shell commands in. - The text that was retrieved from the file. + - `class BetaLocalEnvironment` - - `class BetaResponseComputerToolCall` + - `class BetaContainerReference` - 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. + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the computer call. + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCallOutput` + + The streamed output items emitted by a shell tool call. - `call_id: String` - An identifier used when responding to the tool call with output. + The unique ID of the shell tool call generated by the model. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - The pending safety checks for the computer call. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `id: String` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The ID of the pending safety check. + The exit or timeout outcome associated with this shell call. - - `code: String` + - `class Timeout` - The type of the pending safety check. + Indicates that the shell call exceeded its configured time limit. - - `message: String` + - `type: :timeout` - Details about the pending safety check. + The outcome type. Always `timeout`. - - `status: :in_progress | :completed | :incomplete` + - `:timeout` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class Exit` - - `:in_progress` + Indicates that the shell commands finished and returned an exit code. - - `:completed` + - `exit_code: Integer` - - `:incomplete` + The exit code returned by the shell process. - - `type: :computer_call` + - `type: :exit` - The type of the computer call. Always `computer_call`. + The outcome type. Always `exit`. - - `:computer_call` + - `:exit` - - `action: BetaComputerAction` + - `stderr: String` - A click action. + Captured stderr output for the shell call. - - `class Click` + - `stdout: String` - A click action. + Captured stdout output for the shell call. - - `button: :left | :right | :wheel | 2 more` + - `type: :shell_call_output` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The type of the item. Always `shell_call_output`. - - `:left` + - `:shell_call_output` - - `:right` + - `id: String` - - `:wheel` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `:back` + - `agent: Agent{ agent_name}` - - `:forward` + The agent that produced this item. - - `type: :click` + - `agent_name: String` - Specifies the event type. For a click action, this property is always `click`. + The canonical name of the agent that produced this item. - - `:click` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `x: Integer` + The execution context that produced this tool call. - The x-coordinate where the click occurred. + - `class Direct` - - `y_: Integer` + - `type: :direct` - The y-coordinate where the click occurred. + The caller type. Always `direct`. - - `keys: Array[String]` + - `:direct` - The keys being held while clicking. + - `class Program` - - `class DoubleClick` + - `caller_id: String` - A double click action. + The call ID of the program item that produced this tool call. - - `keys: Array[String]` + - `type: :program` - The keys being held while double-clicking. + The caller type. Always `program`. - - `type: :double_click` + - `:program` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `max_output_length: Integer` - - `:double_click` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `x: Integer` + - `status: :in_progress | :completed | :incomplete` - The x-coordinate where the double click occurred. + The status of the shell call output. - - `y_: Integer` + - `:in_progress` - The y-coordinate where the double click occurred. + - `:completed` - - `class Drag` + - `:incomplete` - A drag action. + - `class ApplyPatchCall` - - `path: Array[Path{ x, y_}]` + A tool call representing a request to create, delete, or update files using diff patches. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `call_id: String` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The unique ID of the apply patch tool call generated by the model. - - `x: Integer` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The x-coordinate. + The specific create, delete, or update instruction for the apply_patch tool call. - - `y_: Integer` + - `class CreateFile` - The y-coordinate. + Instruction for creating a new file via the apply_patch tool. - - `type: :drag` + - `diff: String` - Specifies the event type. For a drag action, this property is always set to `drag`. + Unified diff content to apply when creating the file. - - `:drag` + - `path: String` - - `keys: Array[String]` + Path of the file to create relative to the workspace root. - The keys being held while dragging the mouse. + - `type: :create_file` - - `class Keypress` + The operation type. Always `create_file`. - A collection of keypresses the model would like to perform. + - `:create_file` - - `keys: Array[String]` + - `class DeleteFile` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Instruction for deleting an existing file via the apply_patch tool. - - `type: :keypress` + - `path: String` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Path of the file to delete relative to the workspace root. - - `:keypress` + - `type: :delete_file` - - `class Move` + The operation type. Always `delete_file`. - A mouse move action. + - `:delete_file` - - `type: :move` + - `class UpdateFile` - Specifies the event type. For a move action, this property is always set to `move`. + Instruction for updating an existing file via the apply_patch tool. - - `:move` + - `diff: String` - - `x: Integer` + Unified diff content to apply to the existing file. - The x-coordinate to move to. + - `path: String` - - `y_: Integer` + Path of the file to update relative to the workspace root. - The y-coordinate to move to. + - `type: :update_file` - - `keys: Array[String]` + The operation type. Always `update_file`. - The keys being held while moving the mouse. + - `:update_file` - - `class Screenshot` + - `status: :in_progress | :completed` - A screenshot action. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `type: :screenshot` + - `:in_progress` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `:completed` - - `:screenshot` + - `type: :apply_patch_call` - - `class Scroll` + The type of the item. Always `apply_patch_call`. - A scroll action. + - `:apply_patch_call` - - `scroll_x: Integer` + - `id: String` - The horizontal scroll distance. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `scroll_y: Integer` + - `agent: Agent{ agent_name}` - The vertical scroll distance. + The agent that produced this item. - - `type: :scroll` + - `agent_name: String` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The canonical name of the agent that produced this item. - - `:scroll` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `x: Integer` + The execution context that produced this tool call. - The x-coordinate where the scroll occurred. + - `class Direct` - - `y_: Integer` + - `type: :direct` - The y-coordinate where the scroll occurred. + The caller type. Always `direct`. - - `keys: Array[String]` + - `:direct` - The keys being held while scrolling. + - `class Program` - - `class Type` + - `caller_id: String` - An action to type in text. + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class ApplyPatchCallOutput` + + 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 | :failed` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `:completed` + + - `:failed` - - `text: String` + - `type: :apply_patch_call_output` - The text to type. + The type of the item. Always `apply_patch_call_output`. - - `type: :type` + - `:apply_patch_call_output` - Specifies the event type. For a type action, this property is always set to `type`. + - `id: String` - - `:type` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class Wait` + - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - `actions: 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. + - `class Direct` - - `class Click` + - `type: :direct` - A click action. + The caller type. Always `direct`. - - `class DoubleClick` + - `:direct` - A double click action. + - `class Program` - - `class Drag` + - `caller_id: String` - A drag action. + The call ID of the program item that produced this tool call. - - `class Keypress` + - `type: :program` - A collection of keypresses the model would like to perform. + The caller type. Always `program`. - - `class Move` + - `:program` - A mouse move action. + - `output: String` - - `class Screenshot` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - A screenshot action. + - `class McpListTools` - - `class Scroll` + A list of tools available on an MCP server. - A scroll action. + - `id: String` - - `class Type` + The unique ID of the list. - An action to type in text. + - `server_label: String` - - `class Wait` + The label of the MCP server. - A wait action. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `agent: Agent{ agent_name}` + The tools available on the server. - The agent that produced this item. + - `input_schema: untyped` - - `agent_name: String` + The JSON schema describing the tool's input. - The canonical name of the agent that produced this item. + - `name: String` - - `class ComputerCallOutput` + The name of the tool. - The output of a computer tool call. + - `annotations: untyped` - - `call_id: String` + Additional annotations about the tool. - The ID of the computer tool call that produced the output. + - `description: String` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The description of the tool. - A computer screenshot image used with the computer use tool. + - `type: :mcp_list_tools` - - `type: :computer_screenshot` + The type of the item. Always `mcp_list_tools`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `:mcp_list_tools` - - `:computer_screenshot` + - `agent: Agent{ agent_name}` - - `file_id: String` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: String` - - `image_url: String` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `error: String` - - `type: :computer_call_output` + Error message if the server could not list tools. - The type of the computer tool call output. Always `computer_call_output`. + - `class McpApprovalRequest` - - `:computer_call_output` + A request for human approval of a tool invocation. - `id: String` - The ID of the computer tool call output. + The unique ID of the approval request. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `arguments: String` - The safety checks reported by the API that have been acknowledged by the developer. + A JSON string of arguments for the tool. - - `id: String` + - `name: String` - The ID of the pending safety check. + The name of the tool to run. - - `code: String` + - `server_label: String` - The type of the pending safety check. + The label of the MCP server making the request. - - `message: String` + - `type: :mcp_approval_request` - Details about the pending safety check. + The type of the item. Always `mcp_approval_request`. + + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -52487,146 +62752,143 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :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` + - `class McpApprovalResponse` - - `:incomplete` + A response to an MCP approval request. - - `class BetaResponseFunctionWebSearch` + - `approval_request_id: 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 ID of the approval request being answered. - - `id: String` + - `approve: bool` - The unique ID of the web search tool call. + Whether the request was approved. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `type: :mcp_approval_response` - 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 item. Always `mcp_approval_response`. - - `class Search` + - `:mcp_approval_response` - Action type "search" - Performs a web search query. + - `id: String` - - `type: :search` + The unique ID of the approval response - The action type. + - `agent: Agent{ agent_name}` - - `:search` + The agent that produced this item. - - `queries: Array[String]` + - `agent_name: String` - The search queries. + The canonical name of the agent that produced this item. - - `query: String` + - `reason: String` - The search query. + Optional reason for the decision. - - `sources: Array[Source{ type, url}]` + - `class McpCall` - The sources used in the search. + An invocation of a tool on an MCP server. - - `type: :url` + - `id: String` - The type of source. Always `url`. + The unique ID of the tool call. - - `:url` + - `arguments: String` - - `url: String` + A JSON string of the arguments passed to the tool. - The URL of the source. + - `name: String` - - `class OpenPage` + The name of the tool that was run. - Action type "open_page" - Opens a specific URL from search results. + - `server_label: String` - - `type: :open_page` + The label of the MCP server running the tool. - The action type. + - `type: :mcp_call` - - `:open_page` + The type of the item. Always `mcp_call`. - - `url: String` + - `:mcp_call` - The URL opened by the model. + - `agent: Agent{ agent_name}` - - `class FindInPage` + The agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `agent_name: String` - - `pattern: String` + The canonical name of the agent that produced this item. - The pattern or text to search for within the page. + - `approval_request_id: String` - - `type: :find_in_page` + 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 action type. + - `error: String` - - `:find_in_page` + The error from the tool call, if any. - - `url: String` + - `output: String` - The URL of the page searched for the pattern. + The output from the tool call. - - `status: :in_progress | :searching | :completed | :failed` + - `status: :in_progress | :completed | :incomplete | 2 more` - The status of the web search tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `:in_progress` - - `:searching` - - `:completed` + - `:incomplete` + + - `:calling` + - `:failed` - - `type: :web_search_call` + - `class BetaResponseCustomToolCallOutput` - The type of the web search tool call. Always `web_search_call`. + The output of a custom tool call from your code, being sent back to the model. - - `:web_search_call` + - `call_id: String` - - `agent: Agent{ 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 | Array[BetaResponseInputText | BetaResponseInputImage | 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. + - `String = String` - - `class BetaResponseFunctionToolCall` + A string of the output of the custom tool call. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `arguments: String` + Text, image, or file output of the custom tool call. - A JSON string of the arguments to pass to the function. + - `class BetaResponseInputText` - - `call_id: String` + A text input to the model. - The unique ID of the function tool call generated by the model. + - `class BetaResponseInputImage` - - `name: String` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The name of the function to run. + - `class BetaResponseInputFile` - - `type: :function_call` + A file input to the model. - The type of the function tool call. Always `function_call`. + - `type: :custom_tool_call_output` - - `:function_call` + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `:custom_tool_call_output` - `id: String` - The unique ID of the function tool call. + The unique ID of the custom tool call output in the OpenAI platform. - `agent: Agent{ agent_name}` @@ -52644,6 +62906,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -52654,162 +62918,131 @@ puts(beta_compacted_response) - `type: :program` - - `:program` - - - `namespace: String` - - The namespace of the function to run. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` + The caller type. Always `program`. - - `:incomplete` + - `:program` - - `class FunctionCallOutput` + - `class BetaResponseCustomToolCall` - The output of a function tool call. + A call to a custom tool created by the model. - `call_id: String` - The unique ID of the function tool call generated by the model. - - - `output: String | BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `String = String` - - A JSON string of the output of the function tool call. - - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - An array of content outputs (text, image, file) for the function tool call. - - - `class BetaResponseInputTextContent` - - A text input to the model. - - - `text: String` + An identifier used to map this custom tool call to a tool call output. - The text input to the model. + - `input: String` - - `type: :input_text` + The input for the custom tool call generated by the model. - The type of the input item. Always `input_text`. + - `name: String` - - `:input_text` + The name of the custom tool being called. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `type: :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. + The type of the custom tool call. Always `custom_tool_call`. - - `mode: :explicit` + - `:custom_tool_call` - The breakpoint mode. Always `explicit`. + - `id: String` - - `:explicit` + The unique ID of the custom tool call in the OpenAI platform. - - `class BetaResponseInputImageContent` + - `agent: Agent{ 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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `detail: :low | :high | :auto | :original` + The execution context that produced this tool call. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class Direct` - - `:low` + - `type: :direct` - - `:high` + - `:direct` - - `:auto` + - `class Program` - - `:original` + - `caller_id: String` - - `file_id: String` + The call ID of the program item that produced this tool call. - The ID of the file to be sent to the model. + - `type: :program` - - `image_url: String` + - `:program` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `namespace: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The namespace of the custom tool being called. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class CompactionTrigger` - - `mode: :explicit` + Compacts the current context. Must be the final input item. - The breakpoint mode. Always `explicit`. + - `type: :compaction_trigger` - - `:explicit` + The type of the item. Always `compaction_trigger`. - - `class BetaResponseInputFileContent` + - `:compaction_trigger` - A file input to the model. + - `agent: Agent{ agent_name}` - - `type: :input_file` + The agent that produced this item. - The type of the input item. Always `input_file`. + - `agent_name: String` - - `:input_file` + The canonical name of the agent that produced this item. - - `detail: :auto | :low | :high` + - `class ItemReference` - 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`. + An internal identifier for an item to reference. - - `:auto` + - `id: String` - - `:low` + The ID of the item to reference. - - `:high` + - `agent: Agent{ agent_name}` - - `file_data: String` + The agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `agent_name: String` - - `file_id: String` + The canonical name of the agent that produced this item. - The ID of the file to be sent to the model. + - `type: :item_reference` - - `file_url: String` + The type of item to reference. Always `item_reference`. - The URL of the file to be sent to the model. + - `:item_reference` - - `filename: String` + - `class Program` - The name of the file to be sent to the model. + - `id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The unique ID of this program 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. + - `call_id: String` - - `mode: :explicit` + The stable call ID of the program item. - The breakpoint mode. Always `explicit`. + - `code: String` - - `:explicit` + The JavaScript source executed by programmatic tool calling. - - `type: :function_call_output` + - `fingerprint: String` - The type of the function tool call output. Always `function_call_output`. + Opaque program replay fingerprint that must be round-tripped. - - `:function_call_output` + - `type: :program` - - `id: String` + The item type. Always `program`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `:program` - `agent: Agent{ agent_name}` @@ -52819,309 +63052,327 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class ProgramOutput` - The execution context that produced this tool call. + - `id: String` - - `class Direct` + The unique ID of this program output item. - - `type: :direct` + - `call_id: String` - The caller type. Always `direct`. + The call ID of the program item. - - `:direct` + - `result: String` - - `class Program` + The result produced by the program item. - - `caller_id: String` + - `status: :completed | :incomplete` - The call ID of the program item that produced this tool call. + The terminal status of the program output. - - `type: :program` + - `:completed` - The caller type. Always `program`. + - `:incomplete` - - `:program` + - `type: :program_output` - - `status: :in_progress | :completed | :incomplete` + The item type. Always `program_output`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `:program_output` - - `:in_progress` + - `agent: Agent{ agent_name}` - - `:completed` + The agent that produced this item. - - `:incomplete` + - `agent_name: String` - - `class AgentMessage` + The canonical name of the agent that produced this item. - A message routed between agents. + - `metadata: Hash[Symbol, String]` - - `author: 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 sending agent identity. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - Plaintext, image, or encrypted content sent between agents. + 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. - - `class BetaResponseInputTextContent` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - A text input to the model. + 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. - - `class BetaResponseInputImageContent` + - `:"gpt-5.6-sol"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:"gpt-5.6-terra"` - - `class EncryptedContent` + - `:"gpt-5.6-luna"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `:"gpt-5.4"` - - `encrypted_content: String` + - `:"gpt-5.4-mini"` - Opaque encrypted content. + - `:"gpt-5.4-nano"` - - `type: :encrypted_content` + - `:"gpt-5.4-mini-2026-03-17"` - The type of the input item. Always `encrypted_content`. + - `:"gpt-5.4-nano-2026-03-17"` - - `:encrypted_content` + - `:"gpt-5.3-chat-latest"` - - `recipient: String` + - `:"gpt-5.2"` - The destination agent identity. + - `:"gpt-5.2-2025-12-11"` - - `type: :agent_message` + - `:"gpt-5.2-chat-latest"` - The item type. Always `agent_message`. + - `:"gpt-5.2-pro"` - - `:agent_message` + - `:"gpt-5.2-pro-2025-12-11"` - - `id: String` + - `:"gpt-5.1"` - The unique ID of this agent message item. + - `:"gpt-5.1-2025-11-13"` - - `agent: Agent{ agent_name}` + - `:"gpt-5.1-codex"` - The agent that produced this item. + - `:"gpt-5.1-mini"` - - `agent_name: String` + - `:"gpt-5.1-chat-latest"` - The canonical name of the agent that produced this item. + - `:"gpt-5"` - - `class MultiAgentCall` + - `:"gpt-5-mini"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:"gpt-5-nano"` - The multi-agent action that was executed. + - `:"gpt-5-2025-08-07"` - - `:spawn_agent` + - `:"gpt-5-mini-2025-08-07"` - - `:interrupt_agent` + - `:"gpt-5-nano-2025-08-07"` - - `:list_agents` + - `:"gpt-5-chat-latest"` - - `:send_message` + - `:"gpt-4.1"` - - `:followup_task` + - `:"gpt-4.1-mini"` - - `:wait_agent` + - `:"gpt-4.1-nano"` - - `arguments: String` + - `:"gpt-4.1-2025-04-14"` - The action arguments as a JSON string. + - `:"gpt-4.1-mini-2025-04-14"` - - `call_id: String` + - `:"gpt-4.1-nano-2025-04-14"` - The unique ID linking this call to its output. + - `:"o4-mini"` - - `type: :multi_agent_call` + - `:"o4-mini-2025-04-16"` - The item type. Always `multi_agent_call`. + - `:o3` - - `:multi_agent_call` + - `:"o3-2025-04-16"` - - `id: String` + - `:"o3-mini"` - The unique ID of this multi-agent call. + - `:"o3-mini-2025-01-31"` - - `agent: Agent{ agent_name}` + - `:o1` - The agent that produced this item. + - `:"o1-2024-12-17"` - - `agent_name: String` + - `:"o1-preview"` - The canonical name of the agent that produced this item. + - `:"o1-preview-2024-09-12"` - - `class MultiAgentCallOutput` + - `:"o1-mini"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:"o1-mini-2024-09-12"` - The multi-agent action that produced this result. + - `:"gpt-4o"` - - `:spawn_agent` + - `:"gpt-4o-2024-11-20"` - - `:interrupt_agent` + - `:"gpt-4o-2024-08-06"` - - `:list_agents` + - `:"gpt-4o-2024-05-13"` - - `:send_message` + - `:"gpt-4o-audio-preview"` - - `:followup_task` + - `:"gpt-4o-audio-preview-2024-10-01"` - - `:wait_agent` + - `:"gpt-4o-audio-preview-2024-12-17"` - - `call_id: String` + - `:"gpt-4o-audio-preview-2025-06-03"` - The unique ID of the multi-agent call. + - `:"gpt-4o-mini-audio-preview"` - - `output: Array[Output{ text, type, annotations}]` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - Text output returned by the multi-agent action. + - `:"gpt-4o-search-preview"` - - `text: String` + - `:"gpt-4o-mini-search-preview"` - The text content. + - `:"gpt-4o-search-preview-2025-03-11"` - - `type: :output_text` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - The content type. Always `output_text`. + - `:"chatgpt-4o-latest"` - - `:output_text` + - `:"codex-mini-latest"` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `:"gpt-4o-mini"` - Citations associated with the text content. + - `:"gpt-4o-mini-2024-07-18"` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `:"gpt-4-turbo"` - - `file_id: String` + - `:"gpt-4-turbo-2024-04-09"` - The ID of the file. + - `:"gpt-4-0125-preview"` - - `filename: String` + - `:"gpt-4-turbo-preview"` - The filename of the file cited. + - `:"gpt-4-1106-preview"` - - `index: Integer` + - `:"gpt-4-vision-preview"` - The index of the file in the list of files. + - `:"gpt-4"` - - `type: :file_citation` + - `:"gpt-4-0314"` - The citation type. Always `file_citation`. + - `:"gpt-4-0613"` - - `:file_citation` + - `:"gpt-4-32k"` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `:"gpt-4-32k-0314"` - - `end_index: Integer` + - `:"gpt-4-32k-0613"` - The index of the last character of the citation in the message. + - `:"gpt-3.5-turbo"` - - `start_index: Integer` + - `:"gpt-3.5-turbo-16k"` - The index of the first character of the citation in the message. + - `:"gpt-3.5-turbo-0301"` - - `title: String` + - `:"gpt-3.5-turbo-0613"` - The title of the cited resource. + - `:"gpt-3.5-turbo-1106"` - - `type: :url_citation` + - `:"gpt-3.5-turbo-0125"` - The citation type. Always `url_citation`. + - `:"gpt-3.5-turbo-16k-0613"` - - `:url_citation` + - `:"o1-pro"` - - `url: String` + - `:"o1-pro-2025-03-19"` - The URL of the cited resource. + - `:"o3-pro"` - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `:"o3-pro-2025-06-10"` - - `container_id: String` + - `:"o3-deep-research"` - The ID of the container. + - `:"o3-deep-research-2025-06-26"` - - `end_index: Integer` + - `:"o4-mini-deep-research"` - The index of the last character of the citation in the message. + - `:"o4-mini-deep-research-2025-06-26"` - - `file_id: String` + - `:"computer-use-preview"` - The ID of the container file. + - `:"computer-use-preview-2025-03-11"` - - `filename: String` + - `:"gpt-5-codex"` - The filename of the container file cited. + - `:"gpt-5-pro"` - - `start_index: Integer` + - `:"gpt-5-pro-2025-10-06"` - The index of the first character of the citation in the message. + - `:"gpt-5.1-codex-max"` - - `type: :container_file_citation` + - `String = String` - The citation type. Always `container_file_citation`. + - `object: :response` - - `:container_file_citation` + The object type of this resource - always set to `response`. - - `type: :multi_agent_call_output` + - `:response` - The item type. Always `multi_agent_call_output`. + - `output: Array[BetaResponseOutputItem]` - - `:multi_agent_call_output` + An array of content items generated by the model. - - `id: 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 unique ID of this multi-agent call output. + - `class BetaResponseOutputMessage` - - `agent: Agent{ agent_name}` + An output message from the model. - The agent that produced this item. + - `class BetaResponseFileSearchToolCall` - - `agent_name: String` + 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 canonical name of the agent that produced this item. + - `class BetaResponseFunctionToolCall` - - `class ToolSearchCall` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `arguments: untyped` + - `class BetaResponseFunctionToolCallOutputItem` - The arguments supplied to the tool search call. + - `id: String` - - `type: :tool_search_call` + The unique ID of the function call tool output. - The item type. Always `tool_search_call`. + - `call_id: String` - - `:tool_search_call` + The unique ID of the function tool call generated by the model. - - `id: String` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The unique ID of this tool search call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `agent: Agent{ agent_name}` + - `String = String` - The agent that produced this item. + A string of the output of the function call. - - `agent_name: String` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The canonical name of the agent that produced this item. + Text, image, or file output of the function call. - - `call_id: String` + - `class BetaResponseInputText` - The unique ID of the tool search call generated by the model. + A text input to the model. - - `execution: :server | :client` + - `class BetaResponseInputImage` - Whether tool search was executed by the server or by the client. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:server` + - `class BetaResponseInputFile` - - `:client` + A file input to the model. - `status: :in_progress | :completed | :incomplete` - The status of the tool search call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -53129,1107 +63380,1062 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseToolSearchOutputItemParam` - - - `tools: Array[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool` - - 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_call_output` - - `name: String` + The type of the function tool call output. Always `function_call_output`. - The name of the function to call. + - `:function_call_output` - - `parameters: Hash[Symbol, untyped]` + - `agent: Agent{ agent_name}` - A JSON schema object describing the parameters of the function. + The agent that produced this item. - - `strict: bool` + - `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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The type of the function tool. Always `function`. + The execution context that produced this tool call. - - `:function` + - `class Direct` - - `allowed_callers: Array[:direct | :programmatic]` + - `type: :direct` - The tool invocation context(s). + The caller type. Always `direct`. - `:direct` - - `:programmatic` + - `class Program` - - `defer_loading: bool` + - `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: String` + - `type: :program` - A description of the function. Used by the model to determine whether or not to call the function. + The caller type. Always `program`. - - `output_schema: Hash[Symbol, untyped]` + - `:program` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `created_by: String` - - `class BetaFileSearchTool` + The identifier of the actor that created the 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). + - `class AgentMessage` - - `type: :file_search` + - `id: String` - The type of the file search tool. Always `file_search`. + The unique ID of the agent message. - - `:file_search` + - `author: String` - - `vector_store_ids: Array[String]` + The sending agent identity. - The IDs of the vector stores to search. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + Encrypted content sent between agents. - A filter to apply. + - `class BetaResponseInputText` - - `class ComparisonFilter` + A text input to the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class BetaResponseOutputText` - - `key: String` + A text output from the model. - The key to compare against the value. + - `class Text` - - `type: :eq | :ne | :gt | 5 more` + A text 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 + - `type: :text` - - `:eq` + - `:text` - - `:ne` + - `class SummaryText` - - `:gt` + A summary text from the model. - - `:gte` + - `text: String` - - `:lt` + A summary of the reasoning output from the model so far. - - `:lte` + - `type: :summary_text` - - `:in` + The type of the object. Always `summary_text`. - - `:nin` + - `:summary_text` - - `value: String | Float | bool | Array[untyped]` + - `class ReasoningText` - The value to compare against the attribute key; supports string, number, or boolean types. + Reasoning text from the model. - - `String = String` + - `text: String` - - `Float = Float` + The reasoning text from the model. - - `UnionMember2 = bool` + - `type: :reasoning_text` - - `UnionMember3 = Array[untyped]` + The type of the reasoning text. Always `reasoning_text`. - - `class CompoundFilter` + - `:reasoning_text` - Combine multiple filters using `and` or `or`. + - `class BetaResponseOutputRefusal` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + A refusal from the model. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `class BetaResponseInputImage` - - `class ComparisonFilter` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class ComputerScreenshot` - - `key: String` + A screenshot of a computer. - The key to compare against the value. + - `detail: :low | :high | :auto | :original` - - `type: :eq | :ne | :gt | 5 more` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `:low` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `:high` - - `:eq` + - `:auto` - - `:ne` + - `:original` - - `:gt` + - `file_id: String` - - `:gte` + The identifier of an uploaded file that contains the screenshot. - - `:lt` + - `image_url: String` - - `:lte` + The URL of the screenshot image. - - `:in` + - `type: :computer_screenshot` - - `:nin` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `value: String | Float | bool | Array[untyped]` + - `:computer_screenshot` - The value to compare against the attribute key; supports string, number, or boolean types. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `String = 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. - - `Float = Float` + - `mode: :explicit` - - `UnionMember2 = bool` + The breakpoint mode. Always `explicit`. - - `UnionMember3 = Array[untyped]` + - `:explicit` - - `UnionMember1 = untyped` + - `class BetaResponseInputFile` - - `type: :and | :or` + A file input to the model. - Type of operation: `and` or `or`. + - `class EncryptedContent` - - `:and` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `:or` + - `encrypted_content: String` - - `max_num_results: Integer` + Opaque encrypted content. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: :encrypted_content` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + The type of the input item. Always `encrypted_content`. - Ranking options for search. + - `:encrypted_content` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `recipient: String` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The destination agent identity. - - `embedding_weight: Float` + - `type: :agent_message` - The weight of the embedding in the reciprocal ranking fusion. + The type of the item. Always `agent_message`. - - `text_weight: Float` + - `:agent_message` - The weight of the text in the reciprocal ranking fusion. + - `agent: Agent{ agent_name}` - - `ranker: :auto | :"default-2024-11-15"` + The agent that produced this item. - 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"` + - `class MultiAgentCall` - - `score_threshold: Float` + - `id: String` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The unique ID of the multi-agent call item. - - `class BetaComputerTool` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The multi-agent action to execute. - - `type: :computer` + - `:spawn_agent` - The type of the computer tool. Always `computer`. + - `:interrupt_agent` - - `:computer` + - `:list_agents` - - `class BetaComputerUsePreviewTool` + - `:send_message` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:followup_task` - - `display_height: Integer` + - `:wait_agent` - The height of the computer display. + - `arguments: String` - - `display_width: Integer` + The JSON string of arguments generated for the action. - The width of the computer display. + - `call_id: String` - - `environment: :windows | :mac | :linux | 2 more` + The unique ID linking this call to its output. - The type of computer environment to control. + - `type: :multi_agent_call` - - `:windows` + The type of the multi-agent call. Always `multi_agent_call`. - - `:mac` + - `:multi_agent_call` - - `:linux` + - `agent: Agent{ 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`. + - `class MultiAgentCallOutput` - - `:computer_use_preview` + - `id: String` - - `class BetaWebSearchTool` + The unique ID of the multi-agent call output 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). + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :web_search | :web_search_2025_08_26` + The multi-agent action that produced this result. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `:spawn_agent` - - `:web_search` + - `:interrupt_agent` - - `:web_search_2025_08_26` + - `:list_agents` - - `filters: Filters{ allowed_domains}` + - `:send_message` - Filters for the search. + - `:followup_task` - - `allowed_domains: Array[String]` + - `:wait_agent` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `call_id: String` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The unique ID of the multi-agent call. - - `search_context_size: :low | :medium | :high` + - `output: Array[BetaResponseOutputText]` - High 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 output returned by the multi-agent action. - - `:low` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:medium` + The annotations of the text output. - - `:high` + - `text: String` - - `user_location: UserLocation{ city, country, region, 2 more}` + The text output from the model. - The approximate location of the user. + - `type: :output_text` - - `city: String` + The type of the output text. Always `output_text`. - Free text input for the city of the user, e.g. `San Francisco`. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `country: String` + - `type: :multi_agent_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 multi-agent result. Always `multi_agent_call_output`. - - `region: String` + - `:multi_agent_call_output` - Free text input for the region of the user, e.g. `California`. + - `agent: Agent{ agent_name}` - - `timezone: 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: :approximate` + The canonical name of the agent that produced this item. - The type of location approximation. Always `approximate`. + - `class BetaResponseFunctionWebSearch` - - `:approximate` + 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. - - `class Mcp` + - `class BetaResponseComputerToolCall` - 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 tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `server_label: String` + - `class BetaResponseComputerToolCallOutputItem` - A label for this MCP server, used to identify it in tool calls. + - `id: String` - - `type: :mcp` + The unique ID of the computer call tool output. - The type of the MCP tool. Always `mcp`. + - `call_id: String` - - `:mcp` + The ID of the computer tool call that produced the output. - - `allowed_callers: Array[:direct | :programmatic]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The tool invocation context(s). + A computer screenshot image used with the computer use tool. - - `:direct` + - `status: :completed | :incomplete | :failed | :in_progress` - - `:programmatic` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `:completed` - List of allowed tool names or a filter object. + - `:incomplete` - - `McpAllowedTools = Array[String]` + - `:failed` - A string array of allowed tool names + - `:in_progress` - - `class McpToolFilter` + - `type: :computer_call_output` - A filter object to specify which tools are allowed. + The type of the computer tool call output. Always `computer_call_output`. - - `read_only: bool` + - `: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. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `tool_names: Array[String]` + The safety checks reported by the API that have been acknowledged by the + developer. - List of allowed tool names. + - `id: String` - - `authorization: String` + The ID of the pending safety check. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `code: String` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + The type of the pending safety check. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `message: String` - Currently supported `connector_id` values are: + Details about the pending safety check. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `agent: Agent{ agent_name}` - - `:connector_dropbox` + The agent that produced this item. - - `:connector_gmail` + - `agent_name: String` - - `:connector_googlecalendar` + The canonical name of the agent that produced this item. - - `:connector_googledrive` + - `created_by: String` - - `:connector_microsoftteams` + The identifier of the actor that created the item. - - `:connector_outlookcalendar` + - `class BetaResponseReasoningItem` - - `:connector_outlookemail` + 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). - - `:connector_sharepoint` + - `class Program` - - `defer_loading: bool` + - `id: String` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the program item. - - `headers: Hash[Symbol, String]` + - `call_id: String` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The stable call ID of the program item. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `code: String` - Specify which of the MCP server's tools require approval. + The JavaScript source executed by programmatic tool calling. - - `class McpToolApprovalFilter` + - `fingerprint: 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. + Opaque program replay fingerprint that must be round-tripped. - - `always: Always{ read_only, tool_names}` + - `type: :program` - A filter object to specify which tools are allowed. + The type of the item. Always `program`. - - `read_only: bool` + - `: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. + - `agent: Agent{ agent_name}` - - `tool_names: Array[String]` + The agent that produced this item. - List of allowed tool names. + - `agent_name: String` - - `never: Never{ read_only, tool_names}` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `class ProgramOutput` - - `read_only: bool` + - `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 program output item. - - `tool_names: Array[String]` + - `call_id: String` - List of allowed tool names. + The call ID of the program item. - - `McpToolApprovalSetting = :always | :never` + - `result: 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 result produced by the program item. - - `:always` + - `status: :completed | :incomplete` - - `:never` + The terminal status of the program output item. - - `server_description: String` + - `:completed` - Optional description of the MCP server, used to provide more context. + - `:incomplete` - - `server_url: String` + - `type: :program_output` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The type of the item. Always `program_output`. - - `tunnel_id: String` + - `:program_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. + - `agent: Agent{ agent_name}` - - `class CodeInterpreter` + 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 | CodeInterpreterToolAuto{ 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. + - `class BetaResponseToolSearchCall` - - `String = String` + - `id: String` - The container ID. + The unique ID of the tool search call item. - - `class CodeInterpreterToolAuto` + - `arguments: untyped` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Arguments used for the tool search call. - - `type: :auto` + - `call_id: String` - Always `auto`. + The unique ID of the tool search call generated by the model. - - `:auto` + - `execution: :server | :client` - - `file_ids: Array[String]` + Whether tool search was executed by the server or by the client. - An optional list of uploaded files to make available to your code. + - `:server` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:client` - The memory limit for the code interpreter container. + - `status: :in_progress | :completed | :incomplete` - - `:"1g"` + The status of the tool search call item that was recorded. - - `:"4g"` + - `:in_progress` - - `:"16g"` + - `:completed` - - `:"64g"` + - `:incomplete` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :tool_search_call` - Network access policy for the container. + The type of the item. Always `tool_search_call`. - - `class BetaContainerNetworkPolicyDisabled` + - `:tool_search_call` - - `type: :disabled` + - `agent: Agent{ agent_name}` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `:disabled` + - `agent_name: String` - - `class BetaContainerNetworkPolicyAllowlist` + The canonical name of the agent that produced this item. - - `allowed_domains: Array[String]` + - `created_by: String` - A list of allowed domains when type is `allowlist`. + The identifier of the actor that created the item. - - `type: :allowlist` + - `class BetaResponseToolSearchOutputItem` - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: String` - - `:allowlist` + The unique ID of the tool search output item. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `call_id: String` - Optional domain-scoped secrets for allowlisted domains. + The unique ID of the tool search call generated by the model. - - `domain: String` + - `execution: :server | :client` - The domain associated with the secret. + Whether tool search was executed by the server or by the client. - - `name: String` + - `:server` - The name of the secret to inject for the domain. + - `:client` - - `value: String` + - `status: :in_progress | :completed | :incomplete` - The secret value to inject for the domain. + The status of the tool search output item that was recorded. - - `type: :code_interpreter` + - `:in_progress` - The type of the code interpreter tool. Always `code_interpreter`. + - `:completed` - - `:code_interpreter` + - `:incomplete` - - `allowed_callers: Array[:direct | :programmatic]` + - `tools: Array[BetaTool]` - The tool invocation context(s). + The loaded tool definitions returned by tool search. - - `:direct` + - `class BetaFunctionTool` - - `:programmatic` + 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). - - `class ProgrammaticToolCalling` + - `class BetaFileSearchTool` - - `type: :programmatic_tool_calling` + 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 tool. Always `programmatic_tool_calling`. + - `class BetaComputerTool` - - `:programmatic_tool_calling` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class ImageGeneration` + - `class BetaComputerUsePreviewTool` - A tool that generates images using the GPT image models. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :image_generation` + - `class BetaWebSearchTool` - The type of the image generation tool. Always `image_generation`. + 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). - - `:image_generation` + - `class Mcp` - - `action: :generate | :edit | :auto` + 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). - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class CodeInterpreter` - - `:generate` + A tool that runs Python code to help generate a response to a prompt. - - `:edit` + - `class ProgrammaticToolCalling` - - `:auto` + - `class ImageGeneration` - - `background: :transparent | :opaque | :auto` + A tool that generates images using the GPT image models. - 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. + - `class LocalShell` - `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 tool that allows the model to execute shell commands in a local environment. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class BetaFunctionShellTool` - - `:transparent` + A tool that allows the model to execute shell commands. - - `:opaque` + - `class BetaCustomTool` - - `: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) - - `input_fidelity: :high | :low` + - `class BetaNamespaceTool` - 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`. + Groups function/custom tools under a shared namespace. - - `:high` + - `class BetaToolSearchTool` - - `:low` + Hosted or BYOT tool search configuration for deferred tools. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `class BetaWebSearchPreviewTool` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `file_id: String` + - `class BetaApplyPatchTool` - File ID for the mask image. + Allows the assistant to create, delete, or update files using unified diffs. - - `image_url: String` + - `type: :tool_search_output` - Base64-encoded mask image. + The type of the item. Always `tool_search_output`. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `:tool_search_output` - The image generation model to use. Default: `gpt-image-1`. + - `agent: Agent{ agent_name}` - - `String = String` + The agent that produced this item. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. - - `:"gpt-image-1"` + - `created_by: String` - - `:"gpt-image-1-mini"` + The identifier of the actor that created the item. - - `:"gpt-image-2"` + - `class AdditionalTools` - - `:"gpt-image-2-2026-04-21"` + - `id: String` - - `:"gpt-image-1.5"` + The unique ID of the additional tools item. - - `:"chatgpt-image-latest"` + - `role: :unknown | :user | :assistant | 5 more` - - `moderation: :auto | :low` + The role that provided the additional tools. - Moderation level for the generated image. Default: `auto`. + - `:unknown` - - `:auto` + - `:user` - - `:low` + - `:assistant` - - `output_compression: Integer` + - `:system` - Compression level for the output image. Default: 100. + - `:critic` - - `output_format: :png | :webp | :jpeg` + - `:discriminator` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `:developer` - - `:png` + - `:tool` - - `:webp` + - `tools: Array[BetaTool]` - - `:jpeg` + The additional tool definitions made available at this item. - - `partial_images: Integer` + - `class BetaFunctionTool` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + 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). - - `quality: :low | :medium | :high | :auto` + - `class BetaFileSearchTool` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `:low` + - `class BetaComputerTool` - - `:medium` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:high` + - `class BetaComputerUsePreviewTool` - - `:auto` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `class BetaWebSearchTool` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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 the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String = String` + - `class Mcp` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + 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 size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class CodeInterpreter` - - `:"1024x1024"` + A tool that runs Python code to help generate a response to a prompt. - - `:"1024x1536"` + - `class ProgrammaticToolCalling` - - `:"1536x1024"` + - `class ImageGeneration` - - `:auto` + A tool that generates images using the GPT image models. - `class LocalShell` A tool that allows the model to execute shell commands in a local environment. - - `type: :local_shell` + - `class BetaFunctionShellTool` - The type of the local shell tool. Always `local_shell`. + A tool that allows the model to execute shell commands. - - `:local_shell` + - `class BetaCustomTool` - - `class BetaFunctionShellTool` + 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 tool that allows the model to execute shell commands. + - `class BetaNamespaceTool` - - `type: :shell` + Groups function/custom tools under a shared namespace. - The type of the shell tool. Always `shell`. + - `class BetaToolSearchTool` - - `:shell` + Hosted or BYOT tool search configuration for deferred tools. - - `allowed_callers: Array[:direct | :programmatic]` + - `class BetaWebSearchPreviewTool` - 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` + - `class BetaApplyPatchTool` - - `:programmatic` + Allows the assistant to create, delete, or update files using unified diffs. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `type: :additional_tools` - - `class BetaContainerAuto` + The type of the item. Always `additional_tools`. - - `type: :container_auto` + - `:additional_tools` - Automatically creates a container for this request + - `agent: Agent{ agent_name}` - - `:container_auto` + The agent that produced this item. - - `file_ids: Array[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: :"1g" | :"4g" | :"16g" | :"64g"` + - `class BetaResponseCompactionItem` - The memory limit for the container. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:"1g"` + - `id: String` - - `:"4g"` + The unique ID of the compaction item. - - `:"16g"` + - `encrypted_content: String` - - `:"64g"` + The encrypted content that was produced by compaction. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :compaction` - Network access policy for the container. + The type of the item. Always `compaction`. - - `class BetaContainerNetworkPolicyDisabled` + - `:compaction` - - `class BetaContainerNetworkPolicyAllowlist` + - `agent: Agent{ agent_name}` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + The agent that produced this item. - An optional list of skills referenced by id or inline data. + - `agent_name: String` - - `class BetaSkillReference` + The canonical name of the agent that produced this item. - - `skill_id: String` + - `created_by: String` - The ID of the referenced skill. + The identifier of the actor that created the item. - - `type: :skill_reference` + - `class ImageGenerationCall` - References a skill created with the /v1/skills endpoint. + An image generation request made by the model. - - `:skill_reference` + - `id: String` - - `version: String` + The unique ID of the image generation call. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `result: String` - - `class BetaInlineSkill` + The generated image encoded in base64. - - `description: String` + - `status: :in_progress | :completed | :generating | :failed` - The description of the skill. + The status of the image generation call. - - `name: String` + - `:in_progress` - The name of the skill. + - `:completed` - - `source: BetaInlineSkillSource` + - `:generating` - Inline skill payload + - `:failed` - - `data: String` + - `type: :image_generation_call` - Base64-encoded skill zip bundle. + The type of the image generation call. Always `image_generation_call`. - - `media_type: :"application/zip"` + - `:image_generation_call` - The media type of the inline skill payload. Must be `application/zip`. + - `agent: Agent{ agent_name}` - - `:"application/zip"` + The agent that produced this item. - - `type: :base64` + - `agent_name: String` - The type of the inline skill source. Must be `base64`. + The canonical name of the agent that produced this item. - - `:base64` + - `class BetaResponseCodeInterpreterToolCall` - - `type: :inline` + A tool call to run code. - Defines an inline skill for this request. + - `class LocalShellCall` - - `:inline` + A tool call to run a command on the local shell. - - `class BetaLocalEnvironment` + - `id: String` - - `type: :local` + The unique ID of the local shell call. - Use a local computer environment. + - `action: Action{ command, env, type, 3 more}` - - `:local` + Execute a shell command on the server. - - `skills: Array[BetaLocalSkill]` + - `command: Array[String]` - An optional list of skills. + The command to run. - - `description: String` + - `env: Hash[Symbol, String]` - The description of the skill. + Environment variables to set for the command. - - `name: String` + - `type: :exec` - The name of the skill. + The type of the local shell action. Always `exec`. - - `path: String` + - `:exec` - The path to the directory containing the skill. + - `timeout_ms: Integer` - - `class BetaContainerReference` + Optional timeout in milliseconds for the command. - - `container_id: String` + - `user: String` - The ID of the referenced container. + Optional user to run the command as. - - `type: :container_reference` + - `working_directory: String` - References a container created with the /v1/containers endpoint + Optional working directory to run the command in. - - `:container_reference` + - `call_id: String` - - `class BetaCustomTool` + The unique ID of the local shell tool call generated by the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `status: :in_progress | :completed | :incomplete` - - `name: String` + The status of the local shell call. - The name of the custom tool, used to identify it in tool calls. + - `:in_progress` - - `type: :custom` + - `:completed` - The type of the custom tool. Always `custom`. + - `:incomplete` - - `:custom` + - `type: :local_shell_call` - - `allowed_callers: Array[:direct | :programmatic]` + The type of the local shell call. Always `local_shell_call`. - The tool invocation context(s). + - `:local_shell_call` - - `:direct` + - `agent: Agent{ agent_name}` - - `:programmatic` + The agent that produced this item. - - `defer_loading: bool` + - `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: String` + - `class LocalShellCallOutput` - Optional description of the custom tool, used to provide more context. + The output of a local shell tool call. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `id: String` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the local shell tool call generated by the model. - - `class Text` + - `output: String` - Unconstrained free-form text. + A JSON string of the output of the local shell tool call. - - `type: :text` + - `type: :local_shell_call_output` - Unconstrained text format. Always `text`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:text` + - `:local_shell_call_output` - - `class Grammar` + - `agent: Agent{ 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 | :regex` + - `status: :in_progress | :completed | :incomplete` - The syntax of the grammar definition. One of `lark` or `regex`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `:lark` + - `:in_progress` - - `:regex` + - `:completed` - - `type: :grammar` + - `:incomplete` - Grammar format. Always `grammar`. + - `class BetaResponseFunctionShellToolCall` - - `:grammar` + A tool call that executes one or more shell commands in a managed environment. - - `class BetaNamespaceTool` + - `id: String` - Groups function/custom tools under a shared namespace. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `description: String` + - `action: Action{ commands, max_output_length, timeout_ms}` - A description of the namespace shown to the model. + The shell commands and limits that describe how to run the tool call. - - `name: String` + - `commands: Array[String]` - The namespace name used in tool calls (for example, `crm`). + - `max_output_length: Integer` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + Optional maximum number of characters to return from each command. - The function/custom tools available inside this namespace. + - `timeout_ms: Integer` - - `class Function` + Optional timeout in milliseconds for the commands. - - `name: String` + - `call_id: String` - - `type: :function` + The unique ID of the shell tool call generated by the model. - - `:function` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `allowed_callers: Array[:direct | :programmatic]` + Represents the use of a local environment to perform shell actions. - The tool invocation context(s). + - `class BetaResponseLocalEnvironment` - - `:direct` + Represents the use of a local environment to perform shell actions. - - `:programmatic` + - `type: :local` - - `defer_loading: bool` + The environment type. Always `local`. - Whether this function should be deferred and discovered via tool search. + - `:local` - - `description: String` + - `class BetaResponseContainerReference` - - `output_schema: Hash[Symbol, untyped]` + Represents a container created with /v1/containers. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `container_id: String` - - `parameters: untyped` + - `type: :container_reference` - - `strict: bool` + The environment type. Always `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. + - `:container_reference` - - `class BetaCustomTool` + - `status: :in_progress | :completed | :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) + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: :namespace` + - `:in_progress` - The type of the tool. Always `namespace`. + - `:completed` - - `:namespace` + - `:incomplete` - - `class BetaToolSearchTool` + - `type: :shell_call` - Hosted or BYOT tool search configuration for deferred tools. + The type of the item. Always `shell_call`. - - `type: :tool_search` + - `:shell_call` - The type of the tool. Always `tool_search`. + - `agent: Agent{ agent_name}` - - `:tool_search` + The agent that produced this item. - - `description: 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: :server | :client` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Whether tool search is executed by the server or by the client. + The execution context that produced this tool call. - - `:server` + - `class Direct` - - `:client` + - `type: :direct` - - `parameters: untyped` + - `:direct` - Parameter schema for a client-executed tool search tool. + - `class Program` - - `class BetaWebSearchPreviewTool` + - `caller_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 that produced this tool call. - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `type: :program` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `:program` - - `:web_search_preview` + - `created_by: String` - - `:web_search_preview_2025_03_11` + The ID of the entity that created this tool call. - - `search_content_types: Array[:text | :image]` + - `class BetaResponseFunctionShellToolCallOutput` - - `:text` + The output of a shell tool call that was emitted. - - `:image` + - `id: String` - - `search_context_size: :low | :medium | :high` + The unique ID of the shell call output. Populated when this item is returned via API. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `call_id: String` - - `:low` + The unique ID of the shell tool call generated by the model. - - `:medium` + - `max_output_length: Integer` - - `:high` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `user_location: UserLocation{ type, city, country, 2 more}` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - The user's location. + An array of shell call output contents - - `type: :approximate` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The type of location approximation. Always `approximate`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `:approximate` + - `class Timeout` - - `city: String` + Indicates that the shell call exceeded its configured time limit. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: :timeout` - - `country: String` + The outcome type. Always `timeout`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `:timeout` - - `region: String` + - `class Exit` - Free text input for the region of the user, e.g. `California`. + Indicates that the shell commands finished and returned an exit code. - - `timezone: String` + - `exit_code: Integer` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Exit code from the shell process. - - `class BetaApplyPatchTool` + - `type: :exit` - Allows the assistant to create, delete, or update files using unified diffs. + The outcome type. Always `exit`. - - `type: :apply_patch` + - `:exit` - The type of the tool. Always `apply_patch`. + - `stderr: String` - - `:apply_patch` + The standard error output that was captured. - - `allowed_callers: Array[:direct | :programmatic]` + - `stdout: String` - The tool invocation context(s). + The standard output that was captured. - - `:direct` + - `created_by: String` - - `:programmatic` + The identifier of the actor that created the item. - - `type: :tool_search_output` + - `status: :in_progress | :completed | :incomplete` - The item type. Always `tool_search_output`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `:tool_search_output` + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of this tool search output. + - `:incomplete` + + - `type: :shell_call_output` + + The type of the shell call output. Always `shell_call_output`. + + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -54239,113 +64445,109 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` - - The unique ID of the tool search call generated by the model. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `execution: :server | :client` + The execution context that produced this tool call. - Whether tool search was executed by the server or by the client. + - `class Direct` - - `:server` + - `type: :direct` - - `:client` + - `:direct` - - `status: :in_progress | :completed | :incomplete` + - `class Program` - 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` - - `class AdditionalTools` + - `created_by: String` - - `role: :developer` + The identifier of the actor that created the item. - The role that provided the additional tools. Only `developer` is supported. + - `class BetaResponseApplyPatchToolCall` - - `:developer` + A tool call that applies file diffs by creating, deleting, or updating files. - - `tools: Array[BetaTool]` + - `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. - - `class BetaFunctionTool` + - `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. - - `class BetaFileSearchTool` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, 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). + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class BetaComputerTool` + - `class CreateFile` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Instruction describing how to create a file via the apply_patch tool. - - `class BetaComputerUsePreviewTool` + - `diff: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Diff to apply. - - `class BetaWebSearchTool` + - `path: 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). + Path of the file to create. - - `class Mcp` + - `type: :create_file` - 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). + Create a new file with the provided diff. - - `class CodeInterpreter` + - `:create_file` - A tool that runs Python code to help generate a response to a prompt. + - `class DeleteFile` - - `class ProgrammaticToolCalling` + Instruction describing how to delete a file via the apply_patch tool. - - `class ImageGeneration` + - `path: String` - A tool that generates images using the GPT image models. + Path of the file to delete. - - `class LocalShell` + - `type: :delete_file` - A tool that allows the model to execute shell commands in a local environment. + Delete the specified file. - - `class BetaFunctionShellTool` + - `:delete_file` - A tool that allows the model to execute shell commands. + - `class UpdateFile` - - `class BetaCustomTool` + Instruction describing how to update a 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) + - `diff: String` - - `class BetaNamespaceTool` + Diff to apply. - Groups function/custom tools under a shared namespace. + - `path: String` - - `class BetaToolSearchTool` + Path of the file to update. - Hosted or BYOT tool search configuration for deferred tools. + - `type: :update_file` - - `class BetaWebSearchPreviewTool` + Update an existing file with the provided diff. - 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). + - `:update_file` - - `class BetaApplyPatchTool` + - `status: :in_progress | :completed` - Allows the assistant to create, delete, or update files using unified diffs. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `type: :additional_tools` + - `:in_progress` - The item type. Always `additional_tools`. + - `:completed` - - `:additional_tools` + - `type: :apply_patch_call` - - `id: String` + The type of the item. Always `apply_patch_call`. - The unique ID of this additional tools item. + - `:apply_patch_call` - `agent: Agent{ agent_name}` @@ -54355,36 +64557,55 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The execution context that produced this tool call. - - `id: String` + - `class Direct` - The unique identifier of the reasoning content. + - `type: :direct` - - `summary: Array[Summary{ text, type}]` + - `:direct` - Reasoning summary content. + - `class Program` - - `text: String` + - `caller_id: String` - A summary of the reasoning output from the model so far. + The call ID of the program item that produced this tool call. - - `type: :summary_text` + - `type: :program` - The type of the object. Always `summary_text`. + - `:program` - - `:summary_text` + - `created_by: String` - - `type: :reasoning` + The ID of the entity that created this tool call. - The type of the object. Always `reasoning`. + - `class BetaResponseApplyPatchToolCallOutput` - - `:reasoning` + 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 | :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: Agent{ agent_name}` @@ -54394,53 +64615,59 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `content: Array[Content{ text, type}]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Reasoning text content. + The execution context that produced this tool call. - - `text: String` + - `class Direct` - The reasoning text from the model. + - `type: :direct` - - `type: :reasoning_text` + - `:direct` - The type of the reasoning text. Always `reasoning_text`. + - `class Program` - - `:reasoning_text` + - `caller_id: String` - - `encrypted_content: String` + The call ID of the program item that produced this tool call. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: :program` - - `status: :in_progress | :completed | :incomplete` + - `:program` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `created_by: String` - - `:in_progress` + The ID of the entity that created this tool call output. - - `:completed` + - `output: String` - - `:incomplete` + Optional textual output returned by the apply patch tool. + + - `class McpCall` + + An invocation of a tool on an MCP server. + + - `id: String` + + The unique ID of the tool call. - - `class BetaResponseCompactionItemParam` + - `arguments: String` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A JSON string of the arguments passed to the tool. - - `encrypted_content: String` + - `name: String` - The encrypted content of the compaction summary. + The name of the tool that was run. - - `type: :compaction` + - `server_label: String` - The type of the item. Always `compaction`. + The label of the MCP server running the tool. - - `:compaction` + - `type: :mcp_call` - - `id: String` + The type of the item. Always `mcp_call`. - The ID of the compaction item. + - `:mcp_call` - `agent: Agent{ agent_name}` @@ -54450,112 +64677,108 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ImageGenerationCall` + - `approval_request_id: String` - An image generation request made by the model. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `id: String` + - `error: String` - The unique ID of the image generation call. + The error from the tool call, if any. - - `result: String` + - `output: String` - The generated image encoded in base64. + The output from the tool call. - - `status: :in_progress | :completed | :generating | :failed` + - `status: :in_progress | :completed | :incomplete | 2 more` - The status of the image generation call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `:in_progress` - `:completed` - - `:generating` - - - `:failed` - - - `type: :image_generation_call` + - `:incomplete` - The type of the image generation call. Always `image_generation_call`. + - `:calling` - - `:image_generation_call` + - `:failed` - - `agent: Agent{ agent_name}` + - `class McpListTools` - The agent that produced this item. + A list of tools available on an MCP server. - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The unique ID of the list. - - `class BetaResponseCodeInterpreterToolCall` + - `server_label: String` - A tool call to run code. + The label of the MCP server. - - `id: String` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - The unique ID of the code interpreter tool call. + The tools available on the server. - - `code: String` + - `input_schema: untyped` - The code to run, or null if not available. + The JSON schema describing the tool's input. - - `container_id: String` + - `name: String` - The ID of the container used to run the code. + The name of the tool. - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `annotations: untyped` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Additional annotations about the tool. - - `class Logs` + - `description: String` - The logs output from the code interpreter. + The description of the tool. - - `logs: String` + - `type: :mcp_list_tools` - The logs output from the code interpreter. + The type of the item. Always `mcp_list_tools`. - - `type: :logs` + - `:mcp_list_tools` - The type of the output. Always `logs`. + - `agent: Agent{ agent_name}` - - `:logs` + The agent that produced this item. - - `class Image` + - `agent_name: String` - The image output from the code interpreter. + The canonical name of the agent that produced this item. - - `type: :image` + - `error: String` - The type of the output. Always `image`. + Error message if the server could not list tools. - - `:image` + - `class McpApprovalRequest` - - `url: String` + A request for human approval of a tool invocation. - The URL of the image output from the code interpreter. + - `id: String` - - `status: :in_progress | :completed | :incomplete | 2 more` + The unique ID of the approval request. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `arguments: String` - - `:in_progress` + A JSON string of arguments for the tool. - - `:completed` + - `name: String` - - `:incomplete` + The name of the tool to run. - - `:interpreting` + - `server_label: String` - - `:failed` + The label of the MCP server making the request. - - `type: :code_interpreter_call` + - `type: :mcp_approval_request` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the item. Always `mcp_approval_request`. - - `:code_interpreter_call` + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -54565,51 +64788,56 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCall` + - `class McpApprovalResponse` - A tool call to run a command on the local shell. + A response to an MCP approval request. - `id: String` - The unique ID of the local shell call. + The unique ID of the approval response - - `action: Action{ command, env, type, 3 more}` + - `approval_request_id: String` - Execute a shell command on the server. + The ID of the approval request being answered. - - `command: Array[String]` + - `approve: bool` - The command to run. + Whether the request was approved. - - `env: Hash[Symbol, String]` + - `type: :mcp_approval_response` - Environment variables to set for the command. + The type of the item. Always `mcp_approval_response`. - - `type: :exec` + - `:mcp_approval_response` - The type of the local shell action. Always `exec`. + - `agent: Agent{ agent_name}` - - `:exec` + The agent that produced this item. - - `timeout_ms: Integer` + - `agent_name: String` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: String` + - `reason: String` - Optional user to run the command as. + Optional reason for the decision. - - `working_directory: String` + - `class BetaResponseCustomToolCall` - Optional working directory to run the command in. + A call to a custom tool created by the model. - - `call_id: String` + - `class BetaResponseCustomToolCallOutputItem` - The unique ID of the local shell tool call generated by the model. + The output of a custom tool call from your code, being sent back to the model. + + - `id: String` + + The unique ID of the custom tool call output item. - `status: :in_progress | :completed | :incomplete` - The status of the local shell call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -54617,829 +64845,943 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :local_shell_call` + - `created_by: String` - The type of the local shell call. Always `local_shell_call`. + The identifier of the actor that created the item. - - `:local_shell_call` + - `parallel_tool_calls: bool` - - `agent: Agent{ agent_name}` + Whether to allow the model to run tool calls in parallel. - The agent that produced this item. + - `temperature: Float` - - `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 | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `class LocalShellCallOutput` + 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 output of a local shell tool call. + - `BetaToolChoiceOptions = :none | :auto | :required` - - `id: String` + Controls which (if any) tool is called by the model. - The unique ID of the local shell tool call generated by the model. + `none` means the model will not call any tool and instead generates a message. - - `output: String` + `auto` means the model can pick between generating a message or calling one or + more tools. - A JSON string of the output of the local shell tool call. + `required` means the model must call one or more tools. - - `type: :local_shell_call_output` + - `:none` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `:auto` - - `:local_shell_call_output` + - `:required` - - `agent: Agent{ agent_name}` + - `class BetaToolChoiceAllowed` - The agent that produced this item. + Constrains the tools available to the model to a pre-defined set. - - `agent_name: String` + - `mode: :auto | :required` - The canonical name of the agent that produced this item. + Constrains the tools available to the model to a pre-defined set. - - `status: :in_progress | :completed | :incomplete` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + `required` requires the model to call one or more of the allowed tools. - - `:in_progress` + - `:auto` - - `:completed` + - `:required` - - `:incomplete` + - `tools: Array[Hash[Symbol, untyped]]` - - `class ShellCall` + A list of tool definitions that the model should be allowed to call. - A tool representing a request to execute one or more shell commands. + For the Responses API, the list of tool definitions might look like: - - `action: Action{ commands, max_output_length, timeout_ms}` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The shell commands and limits that describe how to run the tool call. + - `type: :allowed_tools` - - `commands: Array[String]` + Allowed tool configuration type. Always `allowed_tools`. - Ordered shell commands for the execution environment to run. + - `:allowed_tools` - - `max_output_length: Integer` + - `class BetaToolChoiceTypes` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + 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). - - `timeout_ms: Integer` + - `type: :file_search | :web_search_preview | :computer | 5 more` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `call_id: String` + Allowed values are: - The unique ID of the shell tool call generated by the model. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `type: :shell_call` + - `:file_search` - The type of the item. Always `shell_call`. + - `:web_search_preview` - - `:shell_call` + - `:computer` - - `id: String` + - `:computer_use_preview` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `:computer_use` - - `agent: Agent{ agent_name}` + - `:web_search_preview_2025_03_11` - The agent that produced this item. + - `:image_generation` - - `agent_name: String` + - `:code_interpreter` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceFunction` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Use this option to force the model to call a specific function. - The execution context that produced this tool call. + - `name: String` - - `class Direct` + The name of the function to call. - - `type: :direct` + - `type: :function` - The caller type. Always `direct`. + For function calling, the type is always `function`. - - `:direct` + - `:function` - - `class Program` + - `class BetaToolChoiceMcp` - - `caller_id: String` + Use this option to force the model to call a specific tool on a remote MCP server. - The call ID of the program item that produced this tool call. + - `server_label: String` - - `type: :program` + The label of the MCP server to use. - The caller type. Always `program`. + - `type: :mcp` - - `:program` + For MCP tools, the type is always `mcp`. - - `environment: BetaLocalEnvironment | BetaContainerReference` + - `:mcp` - The environment to execute the shell commands in. + - `name: String` - - `class BetaLocalEnvironment` + The name of the tool to call on the server. - - `class BetaContainerReference` + - `class BetaToolChoiceCustom` - - `status: :in_progress | :completed | :incomplete` + Use this option to force the model to call a specific custom tool. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `name: String` - - `:in_progress` + The name of the custom tool to call. - - `:completed` + - `type: :custom` - - `:incomplete` + For custom tool calling, the type is always `custom`. - - `class ShellCallOutput` + - `:custom` - The streamed output items emitted by a shell tool call. + - `class BetaSpecificProgrammaticToolCallingParam` - - `call_id: String` + - `type: :programmatic_tool_calling` - The unique ID of the shell tool call generated by the model. + The tool to call. Always `programmatic_tool_calling`. - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + - `:programmatic_tool_calling` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `class BetaToolChoiceApplyPatch` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + Forces the model to call the apply_patch tool when executing a tool call. - The exit or timeout outcome associated with this shell call. + - `type: :apply_patch` - - `class Timeout` + The tool to call. Always `apply_patch`. - Indicates that the shell call exceeded its configured time limit. + - `:apply_patch` - - `type: :timeout` + - `class BetaToolChoiceShell` - The outcome type. Always `timeout`. + Forces the model to call the shell tool when a tool call is required. - - `:timeout` + - `type: :shell` - - `class Exit` + The tool to call. Always `shell`. - Indicates that the shell commands finished and returned an exit code. + - `:shell` - - `exit_code: Integer` + - `tools: Array[BetaTool]` - The exit code returned by the shell process. + 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: :exit` + We support the following categories of tools: - The outcome type. Always `exit`. + - **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. - - `:exit` + - `class BetaFunctionTool` - - `stderr: 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). - Captured stderr output for the shell call. + - `class BetaFileSearchTool` - - `stdout: 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). - Captured stdout output for the shell call. + - `class BetaComputerTool` - - `type: :shell_call_output` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the item. Always `shell_call_output`. + - `class BetaComputerUsePreviewTool` - - `:shell_call_output` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: String` + - `class BetaWebSearchTool` - The unique ID of the shell tool call output. Populated when this item is returned via API. + 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: Agent{ agent_name}` + - `class Mcp` - The agent that produced this item. + 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_name: String` + - `class CodeInterpreter` - The canonical name of the agent that produced this item. + A tool that runs Python code to help generate a response to a prompt. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class ProgrammaticToolCalling` - The execution context that produced this tool call. + - `class ImageGeneration` - - `class Direct` + A tool that generates images using the GPT image models. - - `type: :direct` + - `class LocalShell` - The caller type. Always `direct`. + A tool that allows the model to execute shell commands in a local environment. - - `:direct` + - `class BetaFunctionShellTool` - - `class Program` + A tool that allows the model to execute shell commands. - - `caller_id: String` + - `class BetaCustomTool` - The call ID of the program item that produced this tool 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) - - `type: :program` + - `class BetaNamespaceTool` - The caller type. Always `program`. + Groups function/custom tools under a shared namespace. - - `:program` + - `class BetaToolSearchTool` - - `max_output_length: Integer` + Hosted or BYOT tool search configuration for deferred tools. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `class BetaWebSearchPreviewTool` - - `status: :in_progress | :completed | :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 shell call output. + - `class BetaApplyPatchTool` - - `:in_progress` + Allows the assistant to create, delete, or update files using unified diffs. - - `:completed` + - `top_p: Float` - - `: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. - - `class ApplyPatchCall` + We generally recommend altering this or `temperature` but not both. - A tool call representing a request to create, delete, or update files using diff patches. + - `background: bool` - - `call_id: String` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The unique ID of the apply patch tool call generated by the model. + - `completed_at: Float` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The specific create, delete, or update instruction for the apply_patch tool call. + - `conversation: Conversation{ id}` - - `class CreateFile` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - Instruction for creating a new file via the apply_patch tool. + - `id: String` - - `diff: String` + The unique ID of the conversation that this response was associated with. - Unified diff content to apply when creating the file. + - `max_output_tokens: Integer` - - `path: 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). - Path of the file to create relative to the workspace root. + - `max_tool_calls: Integer` - - `type: :create_file` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The operation type. Always `create_file`. + - `moderation: Moderation{ input, output}` - - `:create_file` + Moderation results for the response input and output, if moderated completions were requested. - - `class DeleteFile` + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - Instruction for deleting an existing file via the apply_patch tool. + Moderation for the response input. - - `path: String` + - `class ModerationResult` - Path of the file to delete relative to the workspace root. + A moderation result produced for the response input or output. - - `type: :delete_file` + - `categories: Hash[Symbol, bool]` - The operation type. Always `delete_file`. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:delete_file` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `class UpdateFile` + Which modalities of input are reflected by the score for each category. - Instruction for updating an existing file via the apply_patch tool. + - `:text` - - `diff: String` + - `:image` - Unified diff content to apply to the existing file. + - `category_scores: Hash[Symbol, Float]` - - `path: String` + A dictionary of moderation categories to scores. - Path of the file to update relative to the workspace root. + - `flagged: bool` - - `type: :update_file` + A boolean indicating whether the content was flagged by any category. - The operation type. Always `update_file`. + - `model: String` - - `:update_file` + The moderation model that produced this result. - - `status: :in_progress | :completed` + - `type: :moderation_result` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The object type, which was always `moderation_result` for successful moderation results. - - `:in_progress` + - `:moderation_result` - - `:completed` + - `class Error` - - `type: :apply_patch_call` + An error produced while attempting moderation for the response input or output. - The type of the item. Always `apply_patch_call`. + - `code: String` - - `:apply_patch_call` + The error code. - - `id: String` + - `message: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The error message. - - `agent: Agent{ 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. + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Moderation for the response output. - The execution context that produced this tool call. + - `class ModerationResult` - - `class Direct` + A moderation result produced for the response input or output. - - `type: :direct` + - `categories: Hash[Symbol, bool]` - The caller type. Always `direct`. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:direct` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `class Program` + Which modalities of input are reflected by the score for each category. - - `caller_id: String` + - `:text` - The call ID of the program item that produced this tool call. + - `:image` - - `type: :program` + - `category_scores: Hash[Symbol, Float]` - The caller type. Always `program`. + A dictionary of moderation categories to scores. - - `:program` + - `flagged: bool` - - `class ApplyPatchCallOutput` + A boolean indicating whether the content was flagged by any category. - The streamed output emitted by an apply patch tool call. + - `model: String` - - `call_id: String` + The moderation model that produced this result. - The unique ID of the apply patch tool call generated by the model. + - `type: :moderation_result` - - `status: :completed | :failed` + The object type, which was always `moderation_result` for successful moderation results. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `:moderation_result` - - `:completed` + - `class Error` - - `:failed` + An error produced while attempting moderation for the response input or output. - - `type: :apply_patch_call_output` + - `code: String` - The type of the item. Always `apply_patch_call_output`. + The error code. - - `:apply_patch_call_output` + - `message: String` - - `id: String` + The error message. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `type: :error` - - `agent: Agent{ agent_name}` + The object type, which was always `error` for moderation failures. - The agent that produced this item. + - `:error` - - `agent_name: String` + - `previous_response_id: 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`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `prompt: BetaResponsePrompt` - The execution context that produced this tool call. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `class Direct` + - `id: String` - - `type: :direct` + The unique identifier of the prompt template to use. - The caller type. Always `direct`. + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:direct` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `class Program` + - `String = String` - - `caller_id: String` + - `class BetaResponseInputText` - The call ID of the program item that produced this tool call. + A text input to the model. - - `type: :program` + - `class BetaResponseInputImage` - The caller type. Always `program`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:program` + - `class BetaResponseInputFile` - - `output: String` + A file input to the model. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `version: String` - - `class McpListTools` + Optional version of the prompt template. - A list of tools available on an MCP server. + - `prompt_cache_key: String` - - `id: 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 unique ID of the list. + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `server_label: String` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The label of the MCP server. + - `mode: :implicit | :explicit` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + Whether implicit prompt-cache breakpoints were enabled. - The tools available on the server. + - `:implicit` - - `input_schema: untyped` + - `:explicit` - The JSON schema describing the tool's input. + - `ttl: :"30m"` - - `name: String` + The minimum lifetime applied to each cache breakpoint. - The name of the tool. + - `:"30m"` - - `annotations: untyped` + - `prompt_cache_retention: :in_memory | :"24h"` - Additional annotations about the tool. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `description: 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 description of the tool. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: :mcp_list_tools` + - 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_list_tools`. + - `:in_memory` - - `:mcp_list_tools` + - `:"24h"` - - `agent: Agent{ agent_name}` + - `reasoning: Reasoning{ 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: :auto | :current_turn | :all_turns` - - `error: 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. - Error message if the server could not list tools. + - `:auto` - - `class McpApprovalRequest` + - `:current_turn` - A request for human approval of a tool invocation. + - `:all_turns` - - `id: String` + - `effort: :none | :minimal | :low | 4 more` - The unique ID of the approval request. + 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. - - `arguments: String` + - `:none` - A JSON string of arguments for the tool. + - `:minimal` - - `name: String` + - `:low` - The name of the tool to run. + - `:medium` - - `server_label: String` + - `:high` - The label of the MCP server making the request. + - `:xhigh` - - `type: :mcp_approval_request` + - `:max` - The type of the item. Always `mcp_approval_request`. + - `generate_summary: :auto | :concise | :detailed` - - `:mcp_approval_request` + **Deprecated:** use `summary` instead. - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `:auto` - - `agent_name: String` + - `:concise` - The canonical name of the agent that produced this item. + - `:detailed` - - `class McpApprovalResponse` + - `mode: String | :standard | :pro` - A response to an MCP approval request. + Controls the reasoning execution mode for the request. - - `approval_request_id: String` + When returned on a response, this is the effective execution mode. - The ID of the approval request being answered. + - `String = String` - - `approve: bool` + - `Mode = :standard | :pro` - Whether the request was approved. + Controls the reasoning execution mode for the request. - - `type: :mcp_approval_response` + When returned on a response, this is the effective execution mode. - The type of the item. Always `mcp_approval_response`. + - `:standard` - - `:mcp_approval_response` + - `:pro` - - `id: String` + - `summary: :auto | :concise | :detailed` - The unique ID of the approval response + 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: Agent{ 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` - - `reason: String` + - `safety_identifier: String` - Optional reason for the decision. + 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). - - `class McpCall` + - `service_tier: :auto | :default | :flex | 2 more` - An invocation of a tool on an MCP server. + Specifies the processing type used for serving the request. - - `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](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 unique ID of the 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. - - `arguments: String` + - `:auto` - A JSON string of the arguments passed to the tool. + - `:default` - - `name: String` + - `:flex` - The name of the tool that was run. + - `:scale` - - `server_label: String` + - `:priority` - The label of the MCP server running the tool. + - `status: BetaResponseStatus` - - `type: :mcp_call` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The type of the item. Always `mcp_call`. + - `:completed` - - `:mcp_call` + - `:failed` - - `agent: Agent{ agent_name}` + - `:in_progress` - The agent that produced this item. + - `:cancelled` - - `agent_name: String` + - `:queued` - The canonical name of the agent that produced this item. + - `:incomplete` - - `approval_request_id: String` + - `text: BetaResponseTextConfig` - 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. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `error: String` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The error from the tool call, if any. + - `format_: BetaResponseFormatTextConfig` - - `output: String` + An object specifying the format that the model must output. - The output from 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). - - `status: :in_progress | :completed | :incomplete | 2 more` + The default format is `{ "type": "text" }` with no additional options. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + **Not recommended for gpt-4o and newer models:** - - `:in_progress` + 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. - - `:completed` + - `class Text` - - `:incomplete` + Default response format. Used to generate text responses. - - `:calling` + - `type: :text` - - `:failed` + The type of response format being defined. Always `text`. - - `class BetaResponseCustomToolCallOutput` + - `:text` - The output of a custom tool call from your code, being sent back to the model. + - `class BetaResponseFormatTextJSONSchemaConfig` - - `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. + - `name: String` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `schema: Hash[Symbol, untyped]` - - `String = 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 string of the output of the custom tool call. + - `type: :json_schema` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The type of response format being defined. Always `json_schema`. - Text, image, or file output of the custom tool call. + - `:json_schema` - - `class BetaResponseInputText` + - `description: String` - A text input to the model. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaResponseInputImage` + - `strict: bool` - 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 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). - - `class BetaResponseInputFile` + - `class JSONObject` - A file input to 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: :custom_tool_call_output` + - `type: :json_object` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of response format being defined. Always `json_object`. - - `:custom_tool_call_output` + - `:json_object` - - `id: String` + - `verbosity: :low | :medium | :high` - The unique ID of the custom tool call output in the OpenAI platform. + 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: Agent{ agent_name}` + - `:low` - The agent that produced this item. + - `:medium` - - `agent_name: String` + - `:high` - The canonical name of the agent that produced this item. + - `top_logprobs: Integer` - - `caller_: Direct{ type} | Program{ caller_id, type}` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The execution context that produced this tool call. + - `truncation: :auto | :disabled` - - `class Direct` + The truncation strategy to use for the model response. - - `type: :direct` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The caller type. Always `direct`. + - `:auto` - - `:direct` + - `:disabled` - - `class Program` + - `usage: BetaResponseUsage` - - `caller_id: String` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The call ID of the program item that produced this tool call. + - `input_tokens: Integer` - - `type: :program` + The number of input tokens. - The caller type. Always `program`. + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - - `:program` + A detailed breakdown of the input tokens. - - `class BetaResponseCustomToolCall` + - `cache_write_tokens: Integer` - A call to a custom tool created by the model. + The number of input tokens that were written to the cache. - - `call_id: String` + - `cached_tokens: Integer` - An identifier used to map this custom tool call to a tool call output. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `input: String` + - `output_tokens: Integer` - The input for the custom tool call generated by the model. + The number of output tokens. - - `name: String` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - The name of the custom tool being called. + A detailed breakdown of the output tokens. - - `type: :custom_tool_call` + - `reasoning_tokens: Integer` - The type of the custom tool call. Always `custom_tool_call`. + The number of reasoning tokens. - - `:custom_tool_call` + - `total_tokens: Integer` - - `id: String` + The total number of tokens used. - The unique ID of the custom tool call in the OpenAI platform. + - `user: String` - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `sequence_number: Integer` - - `agent_name: String` + The sequence number of this event. - The canonical name of the agent that produced this item. + - `type: :"response.failed"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The type of the event. Always `response.failed`. - The execution context that produced this tool call. + - `:"response.failed"` - - `class Direct` + - `agent: Agent{ agent_name}` - - `type: :direct` + The agent that owns this multi-agent streaming event. - - `:direct` + - `agent_name: String` - - `class Program` + The canonical name of the agent that produced this item. - - `caller_id: String` +### Beta Response File Search Call Completed Event - The call ID of the program item that produced this tool call. +- `class BetaResponseFileSearchCallCompletedEvent` - - `type: :program` + Emitted when a file search call is completed (results found). - - `:program` + - `item_id: String` - - `namespace: String` + The ID of the output item that the file search call is initiated. - The namespace of the custom tool being called. + - `output_index: Integer` - - `class CompactionTrigger` + The index of the output item that the file search call is initiated. - Compacts the current context. Must be the final input item. + - `sequence_number: Integer` - - `type: :compaction_trigger` + The sequence number of this event. - The type of the item. Always `compaction_trigger`. + - `type: :"response.file_search_call.completed"` - - `:compaction_trigger` + The type of the event. Always `response.file_search_call.completed`. + + - `:"response.file_search_call.completed"` - `agent: Agent{ 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. - - `class ItemReference` +### Beta Response File Search Call In Progress Event - An internal identifier for an item to reference. +- `class BetaResponseFileSearchCallInProgressEvent` - - `id: String` + Emitted when a file search call is initiated. + + - `item_id: String` + + The ID of the output item that the file search call is initiated. + + - `output_index: Integer` + + The index of the output item that the file search call is initiated. + + - `sequence_number: Integer` + + The sequence number of this event. + + - `type: :"response.file_search_call.in_progress"` + + The type of the event. Always `response.file_search_call.in_progress`. - The ID of the item to reference. + - `:"response.file_search_call.in_progress"` - `agent: Agent{ agent_name}` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: String` The canonical name of the agent that produced this item. - - `type: :item_reference` - - The type of item to reference. Always `item_reference`. - - - `:item_reference` - - - `class Program` +### Beta Response File Search Call Searching Event - - `id: String` +- `class BetaResponseFileSearchCallSearchingEvent` - The unique ID of this program item. + Emitted when a file search is currently searching. - - `call_id: String` + - `item_id: String` - The stable call ID of the program item. + The ID of the output item that the file search call is initiated. - - `code: String` + - `output_index: Integer` - The JavaScript source executed by programmatic tool calling. + The index of the output item that the file search call is searching. - - `fingerprint: String` + - `sequence_number: Integer` - Opaque program replay fingerprint that must be round-tripped. + The sequence number of this event. - - `type: :program` + - `type: :"response.file_search_call.searching"` - The item type. Always `program`. + The type of the event. Always `response.file_search_call.searching`. - - `:program` + - `:"response.file_search_call.searching"` - `agent: Agent{ 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. - - `class ProgramOutput` +### Beta Response File Search Tool Call + +- `class BetaResponseFileSearchToolCall` + + 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 this program output item. + The unique ID of the file search tool call. - - `call_id: String` + - `queries: Array[String]` - The call ID of the program item. + The queries used to search for files. - - `result: String` + - `status: :in_progress | :searching | :completed | 2 more` - The result produced by the program item. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `status: :completed | :incomplete` + - `:in_progress` - The terminal status of the program output. + - `:searching` - `:completed` - `:incomplete` - - `type: :program_output` + - `:failed` - The item type. Always `program_output`. + - `type: :file_search_call` - - `:program_output` + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` - `agent: Agent{ agent_name}` @@ -55449,437 +65791,446 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `metadata: Hash[Symbol, String]` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` Set of 16 key-value pairs that can be attached to an object. 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. + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `String = 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. + - `Float = Float` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `UnionMember2 = bool` - 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. + - `file_id: String` - - `:"gpt-5.6-sol"` + The unique ID of the file. - - `:"gpt-5.6-terra"` + - `filename: String` - - `:"gpt-5.6-luna"` + The name of the file. - - `:"gpt-5.4"` + - `score: Float` - - `:"gpt-5.4-mini"` + The relevance score of the file - a value between 0 and 1. - - `:"gpt-5.4-nano"` + - `text: String` - - `:"gpt-5.4-mini-2026-03-17"` + The text that was retrieved from the file. - - `:"gpt-5.4-nano-2026-03-17"` +### Beta Response Format Text Config - - `:"gpt-5.3-chat-latest"` +- `BetaResponseFormatTextConfig = Text{ type} | BetaResponseFormatTextJSONSchemaConfig | JSONObject{ type}` - - `:"gpt-5.2"` + An object specifying the format that the model must output. - - `:"gpt-5.2-2025-12-11"` + 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). - - `:"gpt-5.2-chat-latest"` + The default format is `{ "type": "text" }` with no additional options. - - `:"gpt-5.2-pro"` + **Not recommended for gpt-4o and newer models:** - - `:"gpt-5.2-pro-2025-12-11"` + 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. - - `:"gpt-5.1"` + - `class Text` - - `:"gpt-5.1-2025-11-13"` + Default response format. Used to generate text responses. - - `:"gpt-5.1-codex"` + - `type: :text` - - `:"gpt-5.1-mini"` + The type of response format being defined. Always `text`. - - `:"gpt-5.1-chat-latest"` + - `:text` - - `:"gpt-5"` + - `class BetaResponseFormatTextJSONSchemaConfig` - - `:"gpt-5-mini"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:"gpt-5-nano"` + - `name: String` - - `:"gpt-5-2025-08-07"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `:"gpt-5-mini-2025-08-07"` + - `schema: Hash[Symbol, untyped]` - - `:"gpt-5-nano-2025-08-07"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:"gpt-5-chat-latest"` + - `type: :json_schema` - - `:"gpt-4.1"` + The type of response format being defined. Always `json_schema`. - - `:"gpt-4.1-mini"` + - `:json_schema` - - `:"gpt-4.1-nano"` + - `description: String` - - `:"gpt-4.1-2025-04-14"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `:"gpt-4.1-mini-2025-04-14"` + - `strict: bool` - - `:"gpt-4.1-nano-2025-04-14"` + 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). - - `:"o4-mini"` + - `class JSONObject` - - `:"o4-mini-2025-04-16"` + 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. - - `:o3` + - `type: :json_object` - - `:"o3-2025-04-16"` + The type of response format being defined. Always `json_object`. - - `:"o3-mini"` + - `:json_object` - - `:"o3-mini-2025-01-31"` +### Beta Response Format Text JSON Schema Config - - `:o1` +- `class BetaResponseFormatTextJSONSchemaConfig` - - `:"o1-2024-12-17"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:"o1-preview"` + - `name: String` - - `:"o1-preview-2024-09-12"` + 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. - - `:"o1-mini"` + - `schema: Hash[Symbol, untyped]` - - `:"o1-mini-2024-09-12"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:"gpt-4o"` + - `type: :json_schema` - - `:"gpt-4o-2024-11-20"` + The type of response format being defined. Always `json_schema`. - - `:"gpt-4o-2024-08-06"` + - `:json_schema` - - `:"gpt-4o-2024-05-13"` + - `description: String` - - `:"gpt-4o-audio-preview"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `strict: bool` - - `:"gpt-4o-audio-preview-2024-12-17"` + 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). - - `:"gpt-4o-audio-preview-2025-06-03"` +### Beta Response Function Call Arguments Delta Event - - `:"gpt-4o-mini-audio-preview"` +- `class BetaResponseFunctionCallArgumentsDeltaEvent` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + Emitted when there is a partial function-call arguments delta. - - `:"gpt-4o-search-preview"` + - `delta: String` - - `:"gpt-4o-mini-search-preview"` + The function-call arguments delta that is added. - - `:"gpt-4o-search-preview-2025-03-11"` + - `item_id: String` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + The ID of the output item that the function-call arguments delta is added to. - - `:"chatgpt-4o-latest"` + - `output_index: Integer` - - `:"codex-mini-latest"` + The index of the output item that the function-call arguments delta is added to. - - `:"gpt-4o-mini"` + - `sequence_number: Integer` - - `:"gpt-4o-mini-2024-07-18"` + The sequence number of this event. - - `:"gpt-4-turbo"` + - `type: :"response.function_call_arguments.delta"` - - `:"gpt-4-turbo-2024-04-09"` + The type of the event. Always `response.function_call_arguments.delta`. - - `:"gpt-4-0125-preview"` + - `:"response.function_call_arguments.delta"` - - `:"gpt-4-turbo-preview"` + - `agent: Agent{ agent_name}` - - `:"gpt-4-1106-preview"` + The agent that owns this multi-agent streaming event. - - `:"gpt-4-vision-preview"` + - `agent_name: String` - - `:"gpt-4"` + The canonical name of the agent that produced this item. - - `:"gpt-4-0314"` +### Beta Response Function Call Arguments Done Event - - `:"gpt-4-0613"` +- `class BetaResponseFunctionCallArgumentsDoneEvent` - - `:"gpt-4-32k"` + Emitted when function-call arguments are finalized. - - `:"gpt-4-32k-0314"` + - `arguments: String` - - `:"gpt-4-32k-0613"` + The function-call arguments. - - `:"gpt-3.5-turbo"` + - `item_id: String` - - `:"gpt-3.5-turbo-16k"` + The ID of the item. - - `:"gpt-3.5-turbo-0301"` + - `name: String` - - `:"gpt-3.5-turbo-0613"` + The name of the function that was called. - - `:"gpt-3.5-turbo-1106"` + - `output_index: Integer` - - `:"gpt-3.5-turbo-0125"` + The index of the output item. - - `:"gpt-3.5-turbo-16k-0613"` + - `sequence_number: Integer` - - `:"o1-pro"` + The sequence number of this event. - - `:"o1-pro-2025-03-19"` + - `type: :"response.function_call_arguments.done"` - - `:"o3-pro"` + - `:"response.function_call_arguments.done"` - - `:"o3-pro-2025-06-10"` + - `agent: Agent{ agent_name}` - - `:"o3-deep-research"` + The agent that owns this multi-agent streaming event. - - `:"o3-deep-research-2025-06-26"` + - `agent_name: String` - - `:"o4-mini-deep-research"` + The canonical name of the agent that produced this item. - - `:"o4-mini-deep-research-2025-06-26"` +### Beta Response Function Call Output Item - - `:"computer-use-preview"` +- `BetaResponseFunctionCallOutputItem = BetaResponseInputTextContent | BetaResponseInputImageContent | BetaResponseInputFileContent` - - `:"computer-use-preview-2025-03-11"` + A piece of message content, such as text, an image, or a file. - - `:"gpt-5-codex"` + - `class BetaResponseInputTextContent` - - `:"gpt-5-pro"` + A text input to the model. - - `:"gpt-5-pro-2025-10-06"` + - `text: String` - - `:"gpt-5.1-codex-max"` + The text input to the model. - - `String = String` + - `type: :input_text` - - `object: :response` + The type of the input item. Always `input_text`. - The object type of this resource - always set to `response`. + - `:input_text` - - `:response` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `output: Array[BetaResponseOutputItem]` + Marks the exact end of a reusable 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 array of content items generated by the model. + - `mode: :explicit` - - 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 breakpoint mode. Always `explicit`. - - `class BetaResponseOutputMessage` + - `:explicit` - An output message from the model. + - `class BetaResponseInputImageContent` - - `class BetaResponseFileSearchToolCall` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - 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: :input_image` - - `class BetaResponseFunctionToolCall` + The type of the input item. Always `input_image`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `:input_image` - - `class BetaResponseFunctionToolCallOutputItem` + - `detail: :low | :high | :auto | :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 function call tool output. + - `:low` - - `call_id: String` + - `:high` - The unique ID of the function tool call generated by the model. + - `:auto` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:original` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `file_id: String` - - `String = String` + The ID of the file to be sent to the model. - A string of the output of the function call. + - `image_url: String` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | 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 function call. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class BetaResponseInputText` + Marks the exact end of a reusable 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` - - `class BetaResponseInputImage` + The breakpoint mode. Always `explicit`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:explicit` - - `class BetaResponseInputFile` + - `class BetaResponseInputFileContent` A file input to the model. - - `status: :in_progress | :completed | :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: :auto | :low | :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: :function_call_output` + - `:auto` - The type of the function tool call output. Always `function_call_output`. + - `:low` - - `:function_call_output` + - `:high` - - `agent: Agent{ agent_name}` + - `file_data: String` - The agent that produced this item. + The base64-encoded data of the file to be sent to the model. - - `agent_name: String` + - `file_id: String` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `file_url: String` - The execution context that produced this tool call. + The URL of the file to be sent to the model. - - `class Direct` + - `filename: String` - - `type: :direct` + The name of the file to be sent to the model. - The caller type. Always `direct`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `class Program` + - `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` +### Beta Response Function Call Output Item List - The caller type. Always `program`. +- `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `:program` + An array of content outputs (text, image, file) for the function tool call. - - `created_by: String` + - `class BetaResponseInputTextContent` - The identifier of the actor that created the item. + A text input to the model. - - `class AgentMessage` + - `text: String` - - `id: String` + The text input to the model. - The unique ID of the agent message. + - `type: :input_text` - - `author: String` + The type of the input item. Always `input_text`. - The sending agent identity. + - `:input_text` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - Encrypted content sent between agents. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseInputText` + - `mode: :explicit` - A text input to the model. + The breakpoint mode. Always `explicit`. - - `class BetaResponseOutputText` + - `:explicit` - A text output from the model. + - `class BetaResponseInputImageContent` - - `class Text` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - A text content. + - `type: :input_image` - - `text: String` + The type of the input item. Always `input_image`. - - `type: :text` + - `:input_image` - - `:text` + - `detail: :low | :high | :auto | :original` - - `class SummaryText` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A summary text from the model. + - `:low` - - `text: String` + - `:high` - A summary of the reasoning output from the model so far. + - `:auto` - - `type: :summary_text` + - `:original` - The type of the object. Always `summary_text`. + - `file_id: String` - - `:summary_text` + The ID of the file to be sent to the model. - - `class ReasoningText` + - `image_url: String` - Reasoning text from the model. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `text: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The reasoning text from 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. - - `type: :reasoning_text` + - `mode: :explicit` - The type of the reasoning text. Always `reasoning_text`. + The breakpoint mode. Always `explicit`. - - `:reasoning_text` + - `:explicit` - - `class BetaResponseOutputRefusal` + - `class BetaResponseInputFileContent` - A refusal from the model. + A file input to the model. - - `class BetaResponseInputImage` + - `type: :input_file` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The type of the input item. Always `input_file`. - - `class ComputerScreenshot` + - `:input_file` - A screenshot of a computer. + - `detail: :auto | :low | :high` - - `detail: :low | :high | :auto | :original` + 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 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` - - `:auto` + - `file_data: String` - - `:original` + The base64-encoded data of the file to be sent to the model. - `file_id: String` - The identifier of an uploaded file that contains the screenshot. - - - `image_url: String` + The ID of the file to be sent to the model. - The URL of the screenshot image. + - `file_url: String` - - `type: :computer_screenshot` + The URL 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`. + - `filename: String` - - `:computer_screenshot` + The name of the file to be sent to the model. - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` @@ -55891,282 +66242,288 @@ puts(beta_compacted_response) - `:explicit` - - `class BetaResponseInputFile` +### Beta Response Function Shell Call Output Content - A file input to the model. +- `class BetaResponseFunctionShellCallOutputContent` - - `class EncryptedContent` + Captured stdout and stderr for a portion of a shell tool call output. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `encrypted_content: String` + The exit or timeout outcome associated with this shell call. - Opaque encrypted content. + - `class Timeout` - - `type: :encrypted_content` + Indicates that the shell call exceeded its configured time limit. - The type of the input item. Always `encrypted_content`. + - `type: :timeout` - - `:encrypted_content` + The outcome type. Always `timeout`. - - `recipient: String` + - `:timeout` - The destination agent identity. + - `class Exit` - - `type: :agent_message` + Indicates that the shell commands finished and returned an exit code. - The type of the item. Always `agent_message`. + - `exit_code: Integer` - - `:agent_message` + The exit code returned by the shell process. - - `agent: Agent{ agent_name}` + - `type: :exit` - The agent that produced this item. + The outcome type. Always `exit`. - - `agent_name: String` + - `:exit` - The canonical name of the agent that produced this item. + - `stderr: String` - - `class MultiAgentCall` + Captured stderr output for the shell call. - - `id: String` + - `stdout: String` - The unique ID of the multi-agent call item. + Captured stdout output for the shell call. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` +### Beta Response Function Shell Tool Call - The multi-agent action to execute. +- `class BetaResponseFunctionShellToolCall` - - `:spawn_agent` + A tool call that executes one or more shell commands in a managed environment. - - `:interrupt_agent` + - `id: String` - - `:list_agents` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `:send_message` + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:followup_task` + The shell commands and limits that describe how to run the tool call. - - `:wait_agent` + - `commands: Array[String]` - - `arguments: String` + - `max_output_length: Integer` - The JSON string of arguments generated for the action. + Optional maximum number of characters to return from each command. - - `call_id: String` + - `timeout_ms: Integer` - The unique ID linking this call to its output. + Optional timeout in milliseconds for the commands. - - `type: :multi_agent_call` + - `call_id: String` - The type of the multi-agent call. Always `multi_agent_call`. + The unique ID of the shell tool call generated by the model. - - `:multi_agent_call` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `agent: Agent{ agent_name}` + Represents the use of a local environment to perform shell actions. - The agent that produced this item. + - `class BetaResponseLocalEnvironment` - - `agent_name: String` + Represents the use of a local environment to perform shell actions. - The canonical name of the agent that produced this item. + - `type: :local` - - `class MultiAgentCallOutput` + The environment type. Always `local`. - - `id: String` + - `:local` - The unique ID of the multi-agent call output item. + - `class BetaResponseContainerReference` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + Represents a container created with /v1/containers. - The multi-agent action that produced this result. + - `container_id: String` - - `:spawn_agent` + - `type: :container_reference` - - `:interrupt_agent` + The environment type. Always `container_reference`. - - `:list_agents` + - `:container_reference` - - `:send_message` + - `status: :in_progress | :completed | :incomplete` - - `:followup_task` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:wait_agent` + - `:in_progress` - - `call_id: String` + - `:completed` - The unique ID of the multi-agent call. + - `:incomplete` - - `output: Array[BetaResponseOutputText]` + - `type: :shell_call` - Text output returned by the multi-agent action. + The type of the item. Always `shell_call`. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `:shell_call` - The annotations of the text output. + - `agent: Agent{ agent_name}` - - `text: String` + The agent that produced this item. - The text output from the model. + - `agent_name: String` - - `type: :output_text` + The canonical name of the agent that produced this item. - The type of the output text. Always `output_text`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The execution context that produced this tool call. - - `type: :multi_agent_call_output` + - `class Direct` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `type: :direct` - - `:multi_agent_call_output` + - `:direct` - - `agent: Agent{ agent_name}` + - `class Program` - The agent that produced this item. + - `caller_id: String` - - `agent_name: String` + The call ID of the program item that produced this tool call. - The canonical name of the agent that produced this item. + - `type: :program` - - `class BetaResponseFunctionWebSearch` + - `:program` - 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. + - `created_by: String` - - `class BetaResponseComputerToolCall` + The ID of the entity that created this tool call. - 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 Function Shell Tool Call Output - - `class BetaResponseComputerToolCallOutputItem` +- `class BetaResponseFunctionShellToolCallOutput` + + The output of a shell tool call that was emitted. - `id: String` - The unique ID of the computer call tool output. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: String` - The ID of the computer tool call that produced the output. - - - `output: BetaResponseComputerToolCallOutputScreenshot` + The unique ID of the shell tool call generated by the model. - A computer screenshot image used with the computer use tool. + - `max_output_length: Integer` - - `status: :completed | :incomplete | :failed | :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. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `:completed` + An array of shell call output contents - - `:incomplete` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `:failed` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `:in_progress` + - `class Timeout` - - `type: :computer_call_output` + Indicates that the shell call exceeded its configured time limit. - The type of the computer tool call output. Always `computer_call_output`. + - `type: :timeout` - - `:computer_call_output` + The outcome type. Always `timeout`. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `:timeout` - The safety checks reported by the API that have been acknowledged by the - developer. + - `class Exit` - - `id: String` + Indicates that the shell commands finished and returned an exit code. - The ID of the pending safety check. + - `exit_code: Integer` - - `code: String` + Exit code from the shell process. - The type of the pending safety check. + - `type: :exit` - - `message: String` + The outcome type. Always `exit`. - Details about the pending safety check. + - `:exit` - - `agent: Agent{ agent_name}` + - `stderr: String` - The agent that produced this item. + The standard error output that was captured. - - `agent_name: String` + - `stdout: String` - The canonical name of the agent that produced this item. + The standard output that was captured. - `created_by: String` The identifier of the actor that created the item. - - `class BetaResponseReasoningItem` + - `status: :in_progress | :completed | :incomplete` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `class Program` + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of the program item. + - `:incomplete` - - `call_id: String` + - `type: :shell_call_output` - The stable call ID of the program item. + The type of the shell call output. Always `shell_call_output`. - - `code: String` + - `:shell_call_output` - The JavaScript source executed by programmatic tool calling. + - `agent: Agent{ agent_name}` - - `fingerprint: String` + The agent that produced this item. - Opaque program replay fingerprint that must be round-tripped. + - `agent_name: String` - - `type: :program` + The canonical name of the agent that produced this item. - The type of the item. Always `program`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:program` + The execution context that produced this tool call. - - `agent: Agent{ agent_name}` + - `class Direct` - The agent that produced this item. + - `type: :direct` - - `agent_name: String` + - `:direct` - The canonical name of the agent that produced this item. + - `class Program` - - `class ProgramOutput` + - `caller_id: String` - - `id: String` + The call ID of the program item that produced this tool call. - The unique ID of the program output item. + - `type: :program` - - `call_id: String` + - `:program` - The call ID of the program item. + - `created_by: String` - - `result: String` + The identifier of the actor that created the item. - The result produced by the program item. +### Beta Response Function Tool Call - - `status: :completed | :incomplete` +- `class BetaResponseFunctionToolCall` - The terminal status of the program output item. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:completed` + - `arguments: String` - - `:incomplete` + A JSON string of the arguments to pass to the function. - - `type: :program_output` + - `call_id: String` - The type of the item. Always `program_output`. + The unique ID of the function tool call generated by the model. - - `:program_output` + - `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: String` + + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -56176,31 +66533,34 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the tool search call item. + - `class Direct` - - `arguments: untyped` + - `type: :direct` - Arguments used for the tool search call. + - `:direct` - - `call_id: String` + - `class Program` - The unique ID of the tool search call generated by the model. + - `caller_id: String` - - `execution: :server | :client` + The call ID of the program item that produced this tool call. - Whether tool search was executed by the server or by the client. + - `type: :program` - - `:server` + - `:program` - - `:client` + - `namespace: String` + + The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` - The status of the tool search call 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` @@ -56208,305 +66568,317 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :tool_search_call` +### Beta Response Function Tool Call Item - The type of the item. Always `tool_search_call`. +- `class BetaResponseFunctionToolCallItem` - - `:tool_search_call` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `agent: Agent{ agent_name}` + - `id: String` - The agent that produced this item. + The unique ID of the function tool call. - - `agent_name: String` + - `status: :in_progress | :completed | :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. + + - `:in_progress` + + - `:completed` + + - `:incomplete` - `created_by: String` The identifier of the actor that created the item. - - `class BetaResponseToolSearchOutputItem` +### Beta Response Function Tool Call Output Item + +- `class BetaResponseFunctionToolCallOutputItem` - `id: String` - The unique ID of the tool search output item. + The unique ID of the function call tool output. - `call_id: String` - The unique ID of the tool search call generated by the model. + The unique ID of the function tool call generated by the model. - - `execution: :server | :client` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - Whether tool search was executed by the server or by the client. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:server` + - `String = String` - - `:client` + A string of the output of the function call. - - `status: :in_progress | :completed | :incomplete` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The status of the tool search output item that was recorded. + Text, image, or file output of the function call. - - `:in_progress` + - `class BetaResponseInputText` - - `:completed` + A text input to the model. - - `:incomplete` + - `text: String` - - `tools: Array[BetaTool]` + The text input to the model. - The loaded tool definitions returned by tool search. + - `type: :input_text` - - `class BetaFunctionTool` + The type of the input item. Always `input_text`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `:input_text` - - `class BetaFileSearchTool` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - 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). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaComputerTool` + - `mode: :explicit` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The breakpoint mode. Always `explicit`. - - `class BetaComputerUsePreviewTool` + - `:explicit` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class BetaResponseInputImage` - - `class BetaWebSearchTool` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - 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). + - `detail: :low | :high | :auto | :original` - - `class Mcp` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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). + - `:low` - - `class CodeInterpreter` + - `:high` - A tool that runs Python code to help generate a response to a prompt. + - `:auto` - - `class ProgrammaticToolCalling` + - `:original` - - `class ImageGeneration` + - `type: :input_image` - A tool that generates images using the GPT image models. + The type of the input item. Always `input_image`. - - `class LocalShell` + - `:input_image` - A tool that allows the model to execute shell commands in a local environment. + - `file_id: String` - - `class BetaFunctionShellTool` + The ID of the file to be sent to the model. - A tool that allows the model to execute shell commands. + - `image_url: String` - - `class BetaCustomTool` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data 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) + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class BetaNamespaceTool` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Groups function/custom tools under a shared namespace. + - `mode: :explicit` - - `class BetaToolSearchTool` + The breakpoint mode. Always `explicit`. - Hosted or BYOT tool search configuration for deferred tools. + - `:explicit` - - `class BetaWebSearchPreviewTool` + - `class BetaResponseInputFile` - 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 file input to the model. - - `class BetaApplyPatchTool` + - `type: :input_file` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the input item. Always `input_file`. - - `type: :tool_search_output` + - `:input_file` - The type of the item. Always `tool_search_output`. + - `detail: :auto | :low | :high` - - `:tool_search_output` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `agent: Agent{ 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_data: String` - - `created_by: String` + The content of the file to be sent to the model. - The identifier of the actor that created the item. + - `file_id: String` - - `class AdditionalTools` + The ID of the file to be sent to the model. - - `id: String` + - `file_url: String` - The unique ID of the additional tools item. + The URL of the file to be sent to the model. - - `role: :unknown | :user | :assistant | 5 more` + - `filename: String` - The role that provided the additional tools. + The name of the file to be sent to the model. - - `:unknown` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:user` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:assistant` + - `mode: :explicit` - - `:system` + The breakpoint mode. Always `explicit`. - - `:critic` + - `:explicit` - - `:discriminator` + - `status: :in_progress | :completed | :incomplete` - - `:developer` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:tool` + - `:in_progress` - - `tools: Array[BetaTool]` + - `:completed` - The additional tool definitions made available at this item. + - `:incomplete` - - `class BetaFunctionTool` + - `type: :function_call_output` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of the function tool call output. Always `function_call_output`. - - `class BetaFileSearchTool` + - `:function_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: Agent{ agent_name}` - - `class BetaComputerTool` + 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` - - `class BetaComputerUsePreviewTool` + 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_: Direct{ type} | Program{ caller_id, type}` - - `class BetaWebSearchTool` + The execution context 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). + - `class Direct` - - `class Mcp` + - `type: :direct` - 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 caller type. Always `direct`. - - `class CodeInterpreter` + - `:direct` + + - `class Program` - A tool that runs Python code to help generate a response to a prompt. + - `caller_id: String` - - `class ProgrammaticToolCalling` + The call ID of the program item that produced this tool call. - - `class ImageGeneration` + - `type: :program` - A tool that generates images using the GPT image models. + The caller type. Always `program`. - - `class LocalShell` + - `:program` - A tool that allows the model to execute shell commands in a local environment. + - `created_by: String` - - `class BetaFunctionShellTool` + The identifier of the actor that created the item. - A tool that allows the model to execute shell commands. +### Beta Response Function Web Search - - `class BetaCustomTool` +- `class BetaResponseFunctionWebSearch` - 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 results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `class BetaNamespaceTool` + - `id: String` - Groups function/custom tools under a shared namespace. + The unique ID of the web search tool call. - - `class BetaToolSearchTool` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - Hosted or BYOT tool search configuration for deferred tools. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `class BetaWebSearchPreviewTool` + - `class Search` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Action type "search" - Performs a web search query. - - `class BetaApplyPatchTool` + - `type: :search` - Allows the assistant to create, delete, or update files using unified diffs. + The action type. - - `type: :additional_tools` + - `:search` - The type of the item. Always `additional_tools`. + - `queries: Array[String]` - - `:additional_tools` + The search queries. - - `agent: Agent{ agent_name}` + - `query: String` - The agent that produced this item. + The search query. - - `agent_name: String` + - `sources: Array[Source{ type, url}]` - The canonical name of the agent that produced this item. + The sources used in the search. - - `class BetaResponseCompactionItem` + - `type: :url` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The type of source. Always `url`. - - `id: String` + - `:url` - The unique ID of the compaction item. + - `url: String` - - `encrypted_content: String` + The URL of the source. - The encrypted content that was produced by compaction. + - `class OpenPage` - - `type: :compaction` + Action type "open_page" - Opens a specific URL from search results. - The type of the item. Always `compaction`. + - `type: :open_page` - - `:compaction` + The action type. - - `agent: Agent{ agent_name}` + - `:open_page` - The agent that produced this item. + - `url: String` - - `agent_name: String` + The URL opened by the model. - The canonical name of the agent that produced this item. + - `class FindInPage` - - `created_by: String` + Action type "find_in_page": Searches for a pattern within a loaded page. - The identifier of the actor that created the item. + - `pattern: String` - - `class ImageGenerationCall` + The pattern or text to search for within the page. - An image generation request made by the model. + - `type: :find_in_page` - - `id: String` + The action type. - The unique ID of the image generation call. + - `:find_in_page` - - `result: String` + - `url: String` - The generated image encoded in base64. + The URL of the page searched for the pattern. - - `status: :in_progress | :completed | :generating | :failed` + - `status: :in_progress | :searching | :completed | :failed` - The status of the image generation call. + The status of the web search tool call. - `:in_progress` - - `:completed` + - `:searching` - - `:generating` + - `:completed` - `:failed` - - `type: :image_generation_call` + - `type: :web_search_call` - The type of the image generation call. Always `image_generation_call`. + The type of the web search tool call. Always `web_search_call`. - - `:image_generation_call` + - `:web_search_call` - `agent: Agent{ agent_name}` @@ -56516,399 +66888,421 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` - - A tool call to run code. - - - `class LocalShellCall` - - A tool call to run a command on the local shell. +### Beta Response Image Gen Call Completed Event - - `id: String` +- `class BetaResponseImageGenCallCompletedEvent` - The unique ID of the local shell call. + Emitted when an image generation tool call has completed and the final image is available. - - `action: Action{ command, env, type, 3 more}` + - `item_id: String` - Execute a shell command on the server. + The unique identifier of the image generation item being processed. - - `command: Array[String]` + - `output_index: Integer` - The command to run. + The index of the output item in the response's output array. - - `env: Hash[Symbol, String]` + - `sequence_number: Integer` - Environment variables to set for the command. + The sequence number of this event. - - `type: :exec` + - `type: :"response.image_generation_call.completed"` - The type of the local shell action. Always `exec`. + The type of the event. Always 'response.image_generation_call.completed'. - - `:exec` + - `:"response.image_generation_call.completed"` - - `timeout_ms: Integer` + - `agent: Agent{ agent_name}` - Optional timeout in milliseconds for the command. + The agent that owns this multi-agent streaming event. - - `user: String` + - `agent_name: String` - Optional user to run the command as. + The canonical name of the agent that produced this item. - - `working_directory: String` +### Beta Response Image Gen Call Generating Event - Optional working directory to run the command in. +- `class BetaResponseImageGenCallGeneratingEvent` - - `call_id: String` + Emitted when an image generation tool call is actively generating an image (intermediate state). - The unique ID of the local shell tool call generated by the model. + - `item_id: String` - - `status: :in_progress | :completed | :incomplete` + The unique identifier of the image generation item being processed. - The status of the local shell call. + - `output_index: Integer` - - `:in_progress` + The index of the output item in the response's output array. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of the image generation item being processed. - - `type: :local_shell_call` + - `type: :"response.image_generation_call.generating"` - The type of the local shell call. Always `local_shell_call`. + The type of the event. Always 'response.image_generation_call.generating'. - - `:local_shell_call` + - `:"response.image_generation_call.generating"` - `agent: Agent{ 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. - - `class LocalShellCallOutput` +### Beta Response Image Gen Call In Progress Event - The output of a local shell tool call. +- `class BetaResponseImageGenCallInProgressEvent` - - `id: String` + Emitted when an image generation tool call is in progress. - The unique ID of the local shell tool call generated by the model. + - `item_id: String` - - `output: String` + The unique identifier of the image generation item being processed. - A JSON string of the output of the local shell tool call. + - `output_index: Integer` - - `type: :local_shell_call_output` + The index of the output item in the response's output array. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `sequence_number: Integer` - - `:local_shell_call_output` + The sequence number of the image generation item being processed. + + - `type: :"response.image_generation_call.in_progress"` + + The type of the event. Always 'response.image_generation_call.in_progress'. + + - `:"response.image_generation_call.in_progress"` - `agent: Agent{ 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: :in_progress | :completed | :incomplete` +### Beta Response Image Gen Call Partial Image Event - The status of the item. One of `in_progress`, `completed`, or `incomplete`. +- `class BetaResponseImageGenCallPartialImageEvent` - - `:in_progress` + Emitted when a partial image is available during image generation streaming. - - `:completed` + - `item_id: String` - - `:incomplete` + The unique identifier of the image generation item being processed. - - `class BetaResponseFunctionShellToolCall` + - `output_index: Integer` - A tool call that executes one or more shell commands in a managed environment. + The index of the output item in the response's output array. - - `id: String` + - `partial_image_b64: String` - The unique ID of the shell tool call. Populated when this item is returned via API. + Base64-encoded partial image data, suitable for rendering as an image. - - `action: Action{ commands, max_output_length, timeout_ms}` + - `partial_image_index: Integer` - The shell commands and limits that describe how to run the tool call. + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `commands: Array[String]` + - `sequence_number: Integer` - - `max_output_length: Integer` + The sequence number of the image generation item being processed. - Optional maximum number of characters to return from each command. + - `type: :"response.image_generation_call.partial_image"` - - `timeout_ms: Integer` + The type of the event. Always 'response.image_generation_call.partial_image'. - Optional timeout in milliseconds for the commands. + - `:"response.image_generation_call.partial_image"` - - `call_id: String` + - `agent: Agent{ agent_name}` - The unique ID of the shell tool call generated by the model. + The agent that owns this multi-agent streaming event. - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `agent_name: String` - Represents the use of a local environment to perform shell actions. + The canonical name of the agent that produced this item. - - `class BetaResponseLocalEnvironment` +### Beta Response In Progress Event - Represents the use of a local environment to perform shell actions. +- `class BetaResponseInProgressEvent` - - `type: :local` + Emitted when the response is in progress. - The environment type. Always `local`. + - `response: BetaResponse` - - `:local` + The response that is in progress. - - `class BetaResponseContainerReference` + - `id: String` - Represents a container created with /v1/containers. + Unique identifier for this Response. - - `container_id: String` + - `created_at: Float` - - `type: :container_reference` + Unix timestamp (in seconds) of when this Response was created. - The environment type. Always `container_reference`. + - `error: BetaResponseError` - - `:container_reference` + An error object returned when the model fails to generate a Response. - - `status: :in_progress | :completed | :incomplete` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The error code for the response. - - `:in_progress` + - `:server_error` - - `:completed` + - `:rate_limit_exceeded` - - `:incomplete` + - `:invalid_prompt` - - `type: :shell_call` + - `:bio_policy` - The type of the item. Always `shell_call`. + - `:vector_store_timeout` - - `:shell_call` + - `:invalid_image` - - `agent: Agent{ 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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:image_too_small` - The execution context that produced this tool call. + - `:image_parse_error` - - `class Direct` + - `:image_content_policy_violation` - - `type: :direct` + - `:invalid_image_mode` - - `:direct` + - `:image_file_too_large` - - `class Program` + - `:unsupported_image_media_type` - - `caller_id: String` + - `:empty_image_file` - The call ID of the program item that produced this tool call. + - `:failed_to_download_image` - - `type: :program` + - `:image_file_not_found` - - `:program` + - `message: String` - - `created_by: String` + A human-readable description of the error. - The ID of the entity that created this tool call. + - `incomplete_details: IncompleteDetails{ reason}` - - `class BetaResponseFunctionShellToolCallOutput` + Details about why the response is incomplete. - The output of a shell tool call that was emitted. + - `reason: :max_output_tokens | :content_filter` - - `id: String` + The reason why the response is incomplete. - The unique ID of the shell call output. Populated when this item is returned via API. + - `:max_output_tokens` - - `call_id: String` + - `:content_filter` - The unique ID of the shell tool call generated by the model. + - `instructions: String | Array[BetaResponseInputItem]` - - `max_output_length: Integer` + A system (or developer) message inserted into the model's context. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `String = String` - An array of shell call output contents + A text input to the model, equivalent to a text input with the + `developer` role. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `InputItemList = Array[BetaResponseInputItem]` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + A list of one or many input items to the model, containing + different content types. - - `class Timeout` + - `class BetaEasyInputMessage` - Indicates that the shell call exceeded its configured time limit. + 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: :timeout` + - `content: String | BetaResponseInputMessageContentList` - The outcome type. Always `timeout`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `:timeout` + - `String = String` - - `class Exit` + A text input to the model. - Indicates that the shell commands finished and returned an exit code. + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `exit_code: Integer` + A list of one or many input items to the model, containing different content + types. - Exit code from the shell process. + - `class BetaResponseInputText` - - `type: :exit` + A text input to the model. - The outcome type. Always `exit`. + - `text: String` - - `:exit` + The text input to the model. - - `stderr: String` + - `type: :input_text` - The standard error output that was captured. + The type of the input item. Always `input_text`. - - `stdout: String` + - `:input_text` - The standard output that was captured. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `created_by: 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` - - `status: :in_progress | :completed | :incomplete` + The breakpoint mode. Always `explicit`. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `:explicit` - - `:in_progress` + - `class BetaResponseInputImage` - - `:completed` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:incomplete` + - `detail: :low | :high | :auto | :original` - - `type: :shell_call_output` + 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 shell call output. Always `shell_call_output`. + - `:low` - - `:shell_call_output` + - `:high` - - `agent: Agent{ agent_name}` + - `:auto` - The agent that produced this item. + - `:original` - - `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`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:input_image` - The execution context that produced this tool call. + - `file_id: String` - - `class Direct` + The ID of the file to be sent to the model. - - `type: :direct` + - `image_url: String` - - `:direct` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class Program` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - `:program` + - `:explicit` - - `created_by: String` + - `class BetaResponseInputFile` - The identifier of the actor that created the item. + A file input to the model. - - `class BetaResponseApplyPatchToolCall` + - `type: :input_file` - A tool call that applies file diffs by creating, deleting, or updating files. + The type of the input item. Always `input_file`. - - `id: String` + - `:input_file` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `detail: :auto | :low | :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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `:low` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `:high` - - `class CreateFile` + - `file_data: String` - Instruction describing how to create a file via the apply_patch tool. + The content of the file to be sent to the model. - - `diff: String` + - `file_id: String` - Diff to apply. + The ID of the file to be sent to the model. - - `path: String` + - `file_url: String` - Path of the file to create. + The URL of the file to be sent to the model. - - `type: :create_file` + - `filename: String` - Create a new file with the provided diff. + The name of the file to be sent to the model. - - `:create_file` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class DeleteFile` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Instruction describing how to delete a file via the apply_patch tool. + - `mode: :explicit` - - `path: String` + The breakpoint mode. Always `explicit`. - Path of the file to delete. + - `:explicit` - - `type: :delete_file` + - `role: :user | :assistant | :system | :developer` - Delete the specified file. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `:delete_file` + - `:user` - - `class UpdateFile` + - `:assistant` - Instruction describing how to update a file via the apply_patch tool. + - `:system` - - `diff: String` + - `:developer` - Diff to apply. + - `phase: :commentary | :final_answer` - - `path: 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. - Path of the file to update. + - `:commentary` - - `type: :update_file` + - `:final_answer` - Update an existing file with the provided diff. + - `type: :message` - - `:update_file` + The type of the message input. Always `message`. - - `status: :in_progress | :completed` + - `:message` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `class Message` - - `:in_progress` + 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` - - `type: :apply_patch_call` + A list of one or many input items to the model, containing different content + types. - The type of the item. Always `apply_patch_call`. + - `role: :user | :system | :developer` - - `:apply_patch_call` + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` - `agent: Agent{ agent_name}` @@ -56918,190 +67312,201 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `status: :in_progress | :completed | :incomplete` - The execution context that produced this tool call. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class Direct` + - `:in_progress` - - `type: :direct` + - `:completed` - - `:direct` + - `:incomplete` - - `class Program` + - `type: :message` - - `caller_id: String` + The type of the message input. Always set to `message`. - The call ID of the program item that produced this tool call. + - `:message` - - `type: :program` + - `class BetaResponseOutputMessage` - - `:program` + An output message from the model. - - `created_by: String` + - `id: String` - The ID of the entity that created this tool call. + The unique ID of the output message. - - `class BetaResponseApplyPatchToolCallOutput` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The output emitted by an apply patch tool call. + The content of the output message. - - `id: String` + - `class BetaResponseOutputText` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + A text output from the model. - - `call_id: String` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ 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 | :failed` + - `class FileCitation` - The status of the apply patch tool call output. One of `completed` or `failed`. + A citation to a file. - - `:completed` + - `file_id: String` - - `:failed` + The ID of the file. - - `type: :apply_patch_call_output` + - `filename: String` - The type of the item. Always `apply_patch_call_output`. + The filename of the file cited. - - `:apply_patch_call_output` + - `index: Integer` - - `agent: Agent{ agent_name}` + The index of the file in the list of files. - The agent that produced this item. + - `type: :file_citation` - - `agent_name: String` + The type of the file citation. Always `file_citation`. - The canonical name of the agent that produced this item. + - `:file_citation` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class URLCitation` - The execution context that produced this tool call. + A citation for a web resource used to generate a model response. - - `class Direct` + - `end_index: Integer` - - `type: :direct` + The index of the last character of the URL citation in the message. - - `:direct` + - `start_index: Integer` - - `class Program` + The index of the first character of the URL citation in the message. - - `caller_id: String` + - `title: String` - The call ID of the program item that produced this tool call. + The title of the web resource. - - `type: :program` + - `type: :url_citation` - - `:program` + The type of the URL citation. Always `url_citation`. - - `created_by: String` + - `:url_citation` - The ID of the entity that created this tool call output. + - `url: String` - - `output: String` + The URL of the web resource. - Optional textual output returned by the apply patch tool. + - `class ContainerFileCitation` - - `class McpCall` + A citation for a container file used to generate a model response. - An invocation of a tool on an MCP server. + - `container_id: String` - - `id: String` + The ID of the container file. - The unique ID of the tool call. + - `end_index: Integer` - - `arguments: String` + The index of the last character of the container file citation in the message. - A JSON string of the arguments passed to the tool. + - `file_id: String` - - `name: String` + The ID of the file. - The name of the tool that was run. + - `filename: String` - - `server_label: String` + The filename of the container file cited. - The label of the MCP server running the tool. + - `start_index: Integer` - - `type: :mcp_call` + The index of the first character of the container file citation in the message. - The type of the item. Always `mcp_call`. + - `type: :container_file_citation` - - `:mcp_call` + The type of the container file citation. Always `container_file_citation`. - - `agent: Agent{ agent_name}` + - `:container_file_citation` - The agent that produced this item. + - `class FilePath` - - `agent_name: String` + A path to a file. - The canonical name of the agent that produced this item. + - `file_id: String` - - `approval_request_id: String` + The ID of the file. - 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. + - `index: Integer` - - `error: String` + The index of the file in the list of files. - The error from the tool call, if any. + - `type: :file_path` - - `output: String` + The type of the file path. Always `file_path`. - The output from the tool call. + - `:file_path` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `text: String` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The text output from the model. - - `:in_progress` + - `type: :output_text` - - `:completed` + The type of the output text. Always `output_text`. - - `:incomplete` + - `:output_text` - - `:calling` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `:failed` + - `token: String` - - `class McpListTools` + - `bytes: Array[Integer]` - A list of tools available on an MCP server. + - `logprob: Float` - - `id: String` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - The unique ID of the list. + - `token: String` - - `server_label: String` + - `bytes: Array[Integer]` - The label of the MCP server. + - `logprob: Float` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `class BetaResponseOutputRefusal` - The tools available on the server. + A refusal from the model. - - `input_schema: untyped` + - `refusal: String` - The JSON schema describing the tool's input. + The refusal explanation from the model. - - `name: String` + - `type: :refusal` - The name of the tool. + The type of the refusal. Always `refusal`. - - `annotations: untyped` + - `:refusal` - Additional annotations about the tool. + - `role: :assistant` - - `description: String` + The role of the output message. Always `assistant`. - The description of the tool. + - `:assistant` - - `type: :mcp_list_tools` + - `status: :in_progress | :completed | :incomplete` - The type of the item. Always `mcp_list_tools`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `:mcp_list_tools` + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the output message. Always `message`. + + - `:message` - `agent: Agent{ agent_name}` @@ -57111,35 +67516,49 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `error: String` + - `phase: :commentary | :final_answer` - Error message if the server could not list tools. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class McpApprovalRequest` + - `:commentary` - A request for human approval of a tool invocation. + - `:final_answer` + + - `class BetaResponseFileSearchToolCall` + + 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 approval request. + The unique ID of the file search tool call. - - `arguments: String` + - `queries: Array[String]` - A JSON string of arguments for the tool. + The queries used to search for files. - - `name: String` + - `status: :in_progress | :searching | :completed | 2 more` - The name of the tool to run. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `server_label: String` + - `:in_progress` - The label of the MCP server making the request. + - `:searching` - - `type: :mcp_approval_request` + - `:completed` - The type of the item. Always `mcp_approval_request`. + - `:incomplete` - - `:mcp_approval_request` + - `:failed` + + - `type: :file_search_call` + + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` - `agent: Agent{ agent_name}` @@ -57149,51 +67568,68 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - A response to an MCP approval request. + The results of the file search tool call. - - `id: String` + - `attributes: Hash[Symbol, String | Float | bool]` - The unique ID of the approval response + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `approval_request_id: String` + - `String = String` - The ID of the approval request being answered. + - `Float = Float` - - `approve: bool` + - `UnionMember2 = bool` - Whether the request was approved. + - `file_id: String` - - `type: :mcp_approval_response` + The unique ID of the file. - The type of the item. Always `mcp_approval_response`. + - `filename: String` - - `:mcp_approval_response` + The name of the file. - - `agent: Agent{ agent_name}` + - `score: Float` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - - `reason: String` + - `class BetaResponseComputerToolCall` - Optional reason for the decision. + 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. - - `class BetaResponseCustomToolCall` + - `id: String` - A call to a custom tool created by the model. + The unique ID of the computer call. - - `class BetaResponseCustomToolCallOutputItem` + - `call_id: String` - The output of a custom tool call from your code, being sent back to the model. + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. - `id: String` - The unique ID of the custom tool call output item. + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. - `status: :in_progress | :completed | :incomplete` @@ -57206,935 +67642,904 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` + - `type: :computer_call` - The identifier of the actor that created the item. + The type of the computer call. Always `computer_call`. - - `parallel_tool_calls: bool` + - `:computer_call` - Whether to allow the model to run tool calls in parallel. + - `action: BetaComputerAction` - - `temperature: Float` + A click action. - 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. + - `class Click` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + A click 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. + - `button: :left | :right | :wheel | 2 more` - - `BetaToolChoiceOptions = :none | :auto | :required` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Controls which (if any) tool is called by the model. + - `:left` - `none` means the model will not call any tool and instead generates a message. + - `:right` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `:wheel` - `required` means the model must call one or more tools. + - `:back` - - `:none` + - `:forward` - - `:auto` + - `type: :click` - - `:required` + Specifies the event type. For a click action, this property is always `click`. - - `class BetaToolChoiceAllowed` + - `:click` - Constrains the tools available to the model to a pre-defined set. + - `x: Integer` - - `mode: :auto | :required` + The x-coordinate where the click occurred. - Constrains the tools available to the model to a pre-defined set. + - `y_: Integer` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The y-coordinate where the click occurred. - `required` requires the model to call one or more of the allowed tools. + - `keys: Array[String]` - - `:auto` + The keys being held while clicking. - - `:required` + - `class DoubleClick` - - `tools: Array[Hash[Symbol, untyped]]` + A double click action. - A list of tool definitions that the model should be allowed to call. + - `keys: Array[String]` - For the Responses API, the list of tool definitions might look like: + The keys being held while double-clicking. - ```json + - `type: :double_click` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `:double_click` + + - `x: Integer` + + The x-coordinate where the double click occurred. + + - `y_: Integer` + + The y-coordinate where the double click occurred. + + - `class Drag` + + A drag action. + + - `path: Array[Path{ x, y_}]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } + { x: 100, y: 200 }, + { x: 200, y: 300 } ] ``` - - `type: :allowed_tools` + - `x: Integer` - Allowed tool configuration type. Always `allowed_tools`. + The x-coordinate. - - `:allowed_tools` + - `y_: Integer` - - `class BetaToolChoiceTypes` + The y-coordinate. - 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: :drag` - - `type: :file_search | :web_search_preview | :computer | 5 more` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `:drag` - Allowed values are: + - `keys: Array[String]` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The keys being held while dragging the mouse. - - `:file_search` + - `class Keypress` - - `:web_search_preview` + A collection of keypresses the model would like to perform. - - `:computer` + - `keys: Array[String]` - - `:computer_use_preview` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `:computer_use` + - `type: :keypress` - - `:web_search_preview_2025_03_11` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `:image_generation` + - `:keypress` - - `:code_interpreter` + - `class Move` - - `class BetaToolChoiceFunction` + A mouse move action. - Use this option to force the model to call a specific function. + - `type: :move` - - `name: String` + Specifies the event type. For a move action, this property is always set to `move`. - The name of the function to call. + - `:move` - - `type: :function` + - `x: Integer` - For function calling, the type is always `function`. + The x-coordinate to move to. - - `:function` + - `y_: Integer` - - `class BetaToolChoiceMcp` + The y-coordinate to move to. - Use this option to force the model to call a specific tool on a remote MCP server. + - `keys: Array[String]` - - `server_label: String` + The keys being held while moving the mouse. - The label of the MCP server to use. + - `class Screenshot` - - `type: :mcp` + A screenshot action. - For MCP tools, the type is always `mcp`. + - `type: :screenshot` - - `:mcp` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `name: String` + - `:screenshot` - The name of the tool to call on the server. + - `class Scroll` - - `class BetaToolChoiceCustom` + A scroll action. - Use this option to force the model to call a specific custom tool. + - `scroll_x: Integer` - - `name: String` + The horizontal scroll distance. - The name of the custom tool to call. + - `scroll_y: Integer` - - `type: :custom` + The vertical scroll distance. - For custom tool calling, the type is always `custom`. + - `type: :scroll` - - `:custom` + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class 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` + + - `class Wait` + + A wait action. + + - `type: :wait` - - `class BetaSpecificProgrammaticToolCallingParam` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `type: :programmatic_tool_calling` + - `:wait` - The tool to call. Always `programmatic_tool_calling`. + - `actions: BetaComputerActionList` - - `:programmatic_tool_calling` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `class BetaToolChoiceApplyPatch` + - `class Click` - Forces the model to call the apply_patch tool when executing a tool call. + A click action. - - `type: :apply_patch` + - `class DoubleClick` - The tool to call. Always `apply_patch`. + A double click action. - - `:apply_patch` + - `class Drag` - - `class BetaToolChoiceShell` + A drag action. - Forces the model to call the shell tool when a tool call is required. + - `class Keypress` - - `type: :shell` + A collection of keypresses the model would like to perform. - The tool to call. Always `shell`. + - `class Move` - - `:shell` + A mouse move action. - - `tools: Array[BetaTool]` + - `class Screenshot` - 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 screenshot action. - We support the following categories of tools: + - `class Scroll` - - **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 scroll action. - - `class BetaFunctionTool` + - `class 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). + An action to type in text. - - `class BetaFileSearchTool` + - `class Wait` - 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 wait action. - - `class BetaComputerTool` + - `agent: Agent{ 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. - - `class BetaComputerUsePreviewTool` + - `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. - - `class BetaWebSearchTool` + - `class ComputerCallOutput` - 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 output of a computer tool call. - - `class Mcp` + - `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 ID of the computer tool call that produced the output. - - `class CodeInterpreter` + - `output: BetaResponseComputerToolCallOutputScreenshot` - A tool that runs Python code to help generate a response to a prompt. + A computer screenshot image used with the computer use tool. - - `class ProgrammaticToolCalling` + - `type: :computer_screenshot` - - `class ImageGeneration` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - A tool that generates images using the GPT image models. + - `:computer_screenshot` - - `class LocalShell` + - `file_id: String` - A tool that allows the model to execute shell commands in a local environment. + The identifier of an uploaded file that contains the screenshot. - - `class BetaFunctionShellTool` + - `image_url: String` - A tool that allows the model to execute shell commands. + The URL of the screenshot image. - - `class BetaCustomTool` + - `type: :computer_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) + The type of the computer tool call output. Always `computer_call_output`. - - `class BetaNamespaceTool` + - `:computer_call_output` - Groups function/custom tools under a shared namespace. + - `id: String` - - `class BetaToolSearchTool` + The ID of the computer tool call output. - Hosted or BYOT tool search configuration for deferred tools. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `class BetaWebSearchPreviewTool` + The safety checks reported by the API that have been acknowledged by the developer. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `id: String` - - `class BetaApplyPatchTool` + The ID of the pending safety check. - Allows the assistant to create, delete, or update files using unified diffs. + - `code: String` - - `top_p: Float` + The type of the pending safety check. - 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. + - `message: String` - We generally recommend altering this or `temperature` but not both. + Details about the pending safety check. - - `background: bool` + - `agent: Agent{ 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: Float` + - `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: Conversation{ id}` + - `status: :in_progress | :completed | :incomplete` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + 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 conversation that this response was associated with. + - `:completed` - - `max_output_tokens: Integer` + - `: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). + - `class BetaResponseFunctionWebSearch` - - `max_tool_calls: Integer` + 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 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. + - `id: String` - - `moderation: Moderation{ input, output}` + The unique ID of the web search tool call. - Moderation results for the response input and output, if moderated completions were requested. + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Moderation for the response input. + - `class Search` - - `class ModerationResult` + Action type "search" - Performs a web search query. - A moderation result produced for the response input or output. + - `type: :search` - - `categories: Hash[Symbol, bool]` + The action type. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `:search` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `queries: Array[String]` - Which modalities of input are reflected by the score for each category. + The search queries. - - `:text` + - `query: String` - - `:image` + The search query. - - `category_scores: Hash[Symbol, Float]` + - `sources: Array[Source{ type, url}]` - A dictionary of moderation categories to scores. + The sources used in the search. - - `flagged: bool` + - `type: :url` - A boolean indicating whether the content was flagged by any category. + The type of source. Always `url`. - - `model: String` + - `:url` - The moderation model that produced this result. + - `url: String` - - `type: :moderation_result` + The URL of the source. - The object type, which was always `moderation_result` for successful moderation results. + - `class OpenPage` - - `:moderation_result` + Action type "open_page" - Opens a specific URL from search results. - - `class Error` + - `type: :open_page` - An error produced while attempting moderation for the response input or output. + The action type. - - `code: String` + - `:open_page` - The error code. + - `url: String` - - `message: String` + The URL opened by the model. - The error message. + - `class FindInPage` - - `type: :error` + Action type "find_in_page": Searches for a pattern within a loaded page. - The object type, which was always `error` for moderation failures. + - `pattern: String` - - `:error` + The pattern or text to search for within the page. - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `type: :find_in_page` - Moderation for the response output. + The action type. - - `class ModerationResult` + - `:find_in_page` - A moderation result produced for the response input or output. + - `url: String` - - `categories: Hash[Symbol, bool]` + The URL of the page searched for the pattern. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `status: :in_progress | :searching | :completed | :failed` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The status of the web search tool call. - Which modalities of input are reflected by the score for each category. + - `:in_progress` - - `:text` + - `:searching` - - `:image` + - `:completed` - - `category_scores: Hash[Symbol, Float]` + - `:failed` - A dictionary of moderation categories to scores. + - `type: :web_search_call` - - `flagged: bool` + The type of the web search tool call. Always `web_search_call`. - A boolean indicating whether the content was flagged by any category. + - `:web_search_call` - - `model: String` + - `agent: Agent{ agent_name}` - The moderation model that produced this result. + The agent that produced this item. - - `type: :moderation_result` + - `agent_name: String` - The object type, which was always `moderation_result` for successful moderation results. + The canonical name of the agent that produced this item. - - `:moderation_result` + - `class BetaResponseFunctionToolCall` - - `class Error` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - An error produced while attempting moderation for the response input or output. + - `arguments: String` - - `code: String` + A JSON string of the arguments to pass to the function. - The error code. + - `call_id: String` - - `message: String` + The unique ID of the function tool call generated by the model. - The error message. + - `name: String` - - `type: :error` + The name of the function to run. - The object type, which was always `error` for moderation failures. + - `type: :function_call` - - `:error` + The type of the function tool call. Always `function_call`. - - `previous_response_id: String` + - `:function_call` - 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`. + - `id: String` - - `prompt: BetaResponsePrompt` + The unique ID of the function tool call. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `agent: Agent{ agent_name}` - - `id: String` + The agent that produced this item. - The unique identifier of the prompt template to use. + - `agent_name: String` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The canonical name of 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. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `String = String` + The execution context that produced this tool call. - - `class BetaResponseInputText` + - `class Direct` - A text input to the model. + - `type: :direct` - - `class BetaResponseInputImage` + - `:direct` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class Program` - - `class BetaResponseInputFile` + - `caller_id: String` - A file input to the model. + The call ID of the program item that produced this tool call. - - `version: String` + - `type: :program` - Optional version of the prompt template. + - `:program` - - `prompt_cache_key: String` + - `namespace: 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 namespace of the function to run. - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `status: :in_progress | :completed | :incomplete` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `mode: :implicit | :explicit` + - `:in_progress` - Whether implicit prompt-cache breakpoints were enabled. + - `:completed` - - `:implicit` + - `:incomplete` - - `:explicit` + - `class FunctionCallOutput` - - `ttl: :"30m"` + The output of a function tool call. - The minimum lifetime applied to each cache breakpoint. + - `call_id: String` - - `:"30m"` + The unique ID of the function tool call generated by the model. - - `prompt_cache_retention: :in_memory | :"24h"` + - `output: String | BetaResponseFunctionCallOutputItemList` - Deprecated. Use `prompt_cache_options.ttl` instead. + Text, image, or file output of the function tool call. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](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. + - `String = String` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + A JSON string of the output of the function tool call. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `:in_memory` + An array of content outputs (text, image, file) for the function tool call. - - `:"24h"` + - `class BetaResponseInputTextContent` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + A text input to the model. - **gpt-5 and o-series models only** + - `text: String` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The text input to the model. - - `context: :auto | :current_turn | :all_turns` + - `type: :input_text` - 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 type of the input item. Always `input_text`. - - `:auto` + - `:input_text` - - `:current_turn` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:all_turns` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `effort: :none | :minimal | :low | 4 more` + - `mode: :explicit` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The breakpoint mode. Always `explicit`. - - `:none` + - `:explicit` - - `:minimal` + - `class BetaResponseInputImageContent` - - `:low` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `:medium` + - `type: :input_image` - - `:high` + The type of the input item. Always `input_image`. - - `:xhigh` + - `:input_image` - - `:max` + - `detail: :low | :high | :auto | :original` - - `generate_summary: :auto | :concise | :detailed` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - **Deprecated:** use `summary` instead. + - `:low` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `:high` - `:auto` - - `:concise` + - `:original` - - `:detailed` + - `file_id: String` - - `mode: String | :standard | :pro` + The ID of the file to be sent to the model. - Controls the reasoning execution mode for the request. + - `image_url: String` - When returned on a response, this is the effective execution mode. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `String = String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `Mode = :standard | :pro` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Controls the reasoning execution mode for the request. + - `mode: :explicit` - When returned on a response, this is the effective execution mode. + The breakpoint mode. Always `explicit`. - - `:standard` + - `:explicit` - - `:pro` + - `class BetaResponseInputFileContent` - - `summary: :auto | :concise | :detailed` + A file input to the model. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `type: :input_file` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The type of the input item. Always `input_file`. - - `:auto` + - `:input_file` - - `:concise` + - `detail: :auto | :low | :high` - - `:detailed` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `safety_identifier: String` + - `:auto` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `:low` - - `service_tier: :auto | :default | :flex | 2 more` + - `:high` - Specifies the processing type used for serving the request. + - `file_data: 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'. + The base64-encoded data of the file to be sent to the model. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `file_id: String` - - `:auto` + The ID of the file to be sent to the model. - - `:default` + - `file_url: String` - - `:flex` + The URL of the file to be sent to the model. - - `:scale` + - `filename: String` - - `:priority` + The name of the file to be sent to the model. - - `status: BetaResponseStatus` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:completed` + - `mode: :explicit` - - `:failed` + The breakpoint mode. Always `explicit`. - - `:in_progress` + - `:explicit` - - `:cancelled` + - `type: :function_call_output` - - `:queued` + The type of the function tool call output. Always `function_call_output`. - - `:incomplete` + - `:function_call_output` - - `text: BetaResponseTextConfig` + - `id: String` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The unique ID of the function tool call output. Populated when this item is returned via API. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `agent: Agent{ agent_name}` - - `format_: 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](https://platform.openai.com/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_: Direct{ type} | Program{ 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. + - `class Direct` - - `class Text` + - `type: :direct` - Default response format. Used to generate text responses. + The caller type. Always `direct`. - - `type: :text` + - `:direct` - The type of response format being defined. Always `text`. + - `class Program` - - `:text` + - `caller_id: String` - - `class BetaResponseFormatTextJSONSchemaConfig` + 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` + The caller type. Always `program`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `:program` - - `schema: Hash[Symbol, untyped]` + - `status: :in_progress | :completed | :incomplete` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `type: :json_schema` + - `:in_progress` - The type of response format being defined. Always `json_schema`. + - `:completed` - - `:json_schema` + - `:incomplete` - - `description: String` + - `class AgentMessage` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A message routed between agents. - - `strict: bool` + - `author: String` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The sending agent identity. - - `class JSONObject` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Plaintext, image, or encrypted content sent between agents. - - `type: :json_object` + - `class BetaResponseInputTextContent` - The type of response format being defined. Always `json_object`. + A text input to the model. - - `:json_object` + - `class BetaResponseInputImageContent` - - `verbosity: :low | :medium | :high` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `class EncryptedContent` - - `:low` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `:medium` + - `encrypted_content: String` - - `:high` + Opaque encrypted content. - - `top_logprobs: Integer` + - `type: :encrypted_content` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The type of the input item. Always `encrypted_content`. - - `truncation: :auto | :disabled` + - `:encrypted_content` - The truncation strategy to use for the model response. + - `recipient: String` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The destination agent identity. - - `:auto` + - `type: :agent_message` - - `:disabled` + The item type. Always `agent_message`. - - `usage: BetaResponseUsage` + - `:agent_message` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `id: String` - - `input_tokens: Integer` + The unique ID of this agent message item. - The number of input tokens. + - `agent: Agent{ agent_name}` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + The agent that produced this item. - A detailed breakdown of the input tokens. + - `agent_name: String` - - `cache_write_tokens: Integer` + The canonical name of the agent that produced this item. - The number of input tokens that were written to the cache. + - `class MultiAgentCall` - - `cached_tokens: Integer` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The multi-agent action that was executed. - - `output_tokens: Integer` + - `:spawn_agent` - The number of output tokens. + - `:interrupt_agent` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `:list_agents` - A detailed breakdown of the output tokens. + - `:send_message` - - `reasoning_tokens: Integer` + - `:followup_task` - The number of reasoning tokens. + - `:wait_agent` - - `total_tokens: Integer` + - `arguments: String` - The total number of tokens used. + The action arguments as a JSON string. - - `user: String` + - `call_id: String` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The unique ID linking this call to its output. -### Beta Response Apply Patch Tool Call + - `type: :multi_agent_call` -- `class BetaResponseApplyPatchToolCall` + The item type. Always `multi_agent_call`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `:multi_agent_call` - `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 this multi-agent call. - The unique ID of the apply patch tool call generated by the model. + - `agent: Agent{ agent_name}` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + The agent that produced this item. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `agent_name: String` - - `class CreateFile` + The canonical name of the agent that produced this item. - Instruction describing how to create a file via the apply_patch tool. + - `class MultiAgentCallOutput` - - `diff: String` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - Diff to apply. + The multi-agent action that produced this result. - - `path: String` + - `:spawn_agent` - Path of the file to create. + - `:interrupt_agent` - - `type: :create_file` + - `:list_agents` - Create a new file with the provided diff. + - `:send_message` - - `:create_file` + - `:followup_task` - - `class DeleteFile` + - `:wait_agent` - Instruction describing how to delete a file via the apply_patch tool. + - `call_id: String` - - `path: String` + The unique ID of the multi-agent call. - Path of the file to delete. + - `output: Array[Output{ text, type, annotations}]` - - `type: :delete_file` + Text output returned by the multi-agent action. - Delete the specified file. + - `text: String` - - `:delete_file` + The text content. - - `class UpdateFile` + - `type: :output_text` - Instruction describing how to update a file via the apply_patch tool. + The content type. Always `output_text`. - - `diff: String` + - `:output_text` - Diff to apply. + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `path: String` + Citations associated with the text content. - Path of the file to update. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `type: :update_file` + - `file_id: String` - Update an existing file with the provided diff. + The ID of the file. - - `:update_file` + - `filename: String` - - `status: :in_progress | :completed` + The filename of the file cited. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `index: Integer` - - `:in_progress` + The index of the file in the list of files. - - `:completed` + - `type: :file_citation` - - `type: :apply_patch_call` + The citation type. Always `file_citation`. - The type of the item. Always `apply_patch_call`. + - `:file_citation` - - `:apply_patch_call` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `agent: Agent{ agent_name}` + - `end_index: Integer` - The agent that produced this item. + The index of the last character of the citation in the message. - - `agent_name: String` + - `start_index: Integer` - The canonical name of the agent that produced this item. + The index of the first character of the citation in the message. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `title: String` - The execution context that produced this tool call. + The title of the cited resource. - - `class Direct` + - `type: :url_citation` - - `type: :direct` + The citation type. Always `url_citation`. - - `:direct` + - `:url_citation` - - `class Program` + - `url: String` - - `caller_id: String` + The URL of the cited resource. - The call ID of the program item that produced this tool call. + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `type: :program` + - `container_id: String` - - `:program` + The ID of the container. - - `created_by: String` + - `end_index: Integer` - The ID of the entity that created this tool call. + The index of the last character of the citation in the message. -### Beta Response Apply Patch Tool Call Output + - `file_id: String` -- `class BetaResponseApplyPatchToolCallOutput` + The ID of the container file. - The output emitted by an apply patch tool call. + - `filename: String` - - `id: String` + The filename of the container file cited. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `start_index: Integer` - - `call_id: String` + The index of the first character of the citation in the message. - The unique ID of the apply patch tool call generated by the model. + - `type: :container_file_citation` - - `status: :completed | :failed` + The citation type. Always `container_file_citation`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `:container_file_citation` - - `:completed` + - `type: :multi_agent_call_output` - - `:failed` + The item type. Always `multi_agent_call_output`. - - `type: :apply_patch_call_output` + - `:multi_agent_call_output` - The type of the item. Always `apply_patch_call_output`. + - `id: String` - - `:apply_patch_call_output` + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -58144,1300 +68549,1316 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - - `:direct` - - - `class Program` + - `class ToolSearchCall` - - `caller_id: String` + - `arguments: untyped` - The call ID of the program item that produced this tool call. + The arguments supplied to the tool search call. - - `type: :program` + - `type: :tool_search_call` - - `:program` + The item type. Always `tool_search_call`. - - `created_by: String` + - `:tool_search_call` - The ID of the entity that created this tool call output. + - `id: String` - - `output: String` + The unique ID of this tool search call. - Optional textual output returned by the apply patch tool. + - `agent: Agent{ agent_name}` -### Beta Response Audio Delta Event + The agent that produced this item. -- `class BetaResponseAudioDeltaEvent` + - `agent_name: String` - Emitted when there is a partial audio response. + The canonical name of the agent that produced this item. - - `delta: String` + - `call_id: String` - A chunk of Base64 encoded response audio bytes. + The unique ID of the tool search call generated by the model. - - `sequence_number: Integer` + - `execution: :server | :client` - A sequence number for this chunk of the stream response. + Whether tool search was executed by the server or by the client. - - `type: :"response.audio.delta"` + - `:server` - The type of the event. Always `response.audio.delta`. + - `:client` - - `:"response.audio.delta"` + - `status: :in_progress | :completed | :incomplete` - - `agent: Agent{ agent_name}` + The status of the tool search call. - 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 Audio Done Event + - `class BetaResponseToolSearchOutputItemParam` -- `class BetaResponseAudioDoneEvent` + - `tools: Array[BetaTool]` - Emitted when the audio response is complete. + The loaded tool definitions returned by the tool search output. - - `sequence_number: Integer` + - `class BetaFunctionTool` - The sequence number of the delta. + 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: :"response.audio.done"` + - `name: String` - The type of the event. Always `response.audio.done`. + The name of the function to call. - - `:"response.audio.done"` + - `parameters: Hash[Symbol, untyped]` - - `agent: Agent{ agent_name}` + A JSON schema object describing the parameters of the function. - The agent that owns this multi-agent streaming event. + - `strict: bool` - - `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` -### Beta Response Audio Transcript Delta Event + The type of the function tool. Always `function`. -- `class BetaResponseAudioTranscriptDeltaEvent` + - `:function` - Emitted when there is a partial transcript of audio. + - `allowed_callers: Array[:direct | :programmatic]` - - `delta: String` + The tool invocation context(s). - The partial transcript of the audio response. + - `:direct` - - `sequence_number: Integer` + - `:programmatic` - The sequence number of this event. + - `defer_loading: bool` - - `type: :"response.audio.transcript.delta"` + Whether this function is deferred and loaded via tool search. - The type of the event. Always `response.audio.transcript.delta`. + - `description: String` - - `:"response.audio.transcript.delta"` + A description of the function. Used by the model to determine whether or not to call the function. - - `agent: Agent{ agent_name}` + - `output_schema: Hash[Symbol, untyped]` - The agent that owns this multi-agent streaming event. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `agent_name: String` + - `class BetaFileSearchTool` - 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). -### Beta Response Audio Transcript Done Event + - `type: :file_search` -- `class BetaResponseAudioTranscriptDoneEvent` + The type of the file search tool. Always `file_search`. - Emitted when the full audio transcript is completed. + - `:file_search` - - `sequence_number: Integer` + - `vector_store_ids: Array[String]` - The sequence number of this event. + The IDs of the vector stores to search. - - `type: :"response.audio.transcript.done"` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - The type of the event. Always `response.audio.transcript.done`. + A filter to apply. - - `:"response.audio.transcript.done"` + - `class ComparisonFilter` - - `agent: Agent{ agent_name}` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The agent that owns this multi-agent streaming event. + - `key: String` - - `agent_name: String` + The key to compare against the value. - The canonical name of the agent that produced this item. + - `type: :eq | :ne | :gt | 5 more` -### Beta Response Code Interpreter Call Code Delta Event + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. -- `class BetaResponseCodeInterpreterCallCodeDeltaEvent` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Emitted when a partial code snippet is streamed by the code interpreter. + - `:eq` - - `delta: String` + - `:ne` - The partial code snippet being streamed by the code interpreter. + - `:gt` - - `item_id: String` + - `:gte` - The unique identifier of the code interpreter tool call item. + - `:lt` - - `output_index: Integer` + - `:lte` - The index of the output item in the response for which the code is being streamed. + - `:in` - - `sequence_number: Integer` + - `:nin` - The sequence number of this event, used to order streaming events. + - `value: String | Float | bool | Array[String | Float]` - - `type: :"response.code_interpreter_call_code.delta"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `String = String` - - `:"response.code_interpreter_call_code.delta"` + - `Float = Float` - - `agent: Agent{ agent_name}` + - `UnionMember2 = bool` - The agent that owns this multi-agent streaming event. + - `UnionMember3 = Array[String | Float]` - - `agent_name: String` + - `String = String` - The canonical name of the agent that produced this item. + - `Float = Float` -### Beta Response Code Interpreter Call Code Done Event + - `class CompoundFilter` -- `class BetaResponseCodeInterpreterCallCodeDoneEvent` + Combine multiple filters using `and` or `or`. - Emitted when the code snippet is finalized by the code interpreter. + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `code: String` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The final code snippet output by the code interpreter. + - `class ComparisonFilter` - - `item_id: String` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique identifier of the code interpreter tool call item. + - `key: String` - - `output_index: Integer` + The key to compare against the value. - The index of the output item in the response for which the code is finalized. + - `type: :eq | :ne | :gt | 5 more` - - `sequence_number: Integer` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The sequence number of this event, used to order streaming events. + - `eq`: equals + - `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: :"response.code_interpreter_call_code.done"` + - `:eq` - The type of the event. Always `response.code_interpreter_call_code.done`. + - `:ne` - - `:"response.code_interpreter_call_code.done"` + - `:gt` - - `agent: Agent{ agent_name}` + - `:gte` - The agent that owns this multi-agent streaming event. + - `:lt` - - `agent_name: String` + - `:lte` - The canonical name of the agent that produced this item. + - `:in` -### Beta Response Code Interpreter Call Completed Event + - `:nin` -- `class BetaResponseCodeInterpreterCallCompletedEvent` + - `value: String | Float | bool | Array[String | Float]` - Emitted when the code interpreter call is completed. + The value to compare against the attribute key; supports string, number, or boolean types. - - `item_id: String` + - `String = String` - The unique identifier of the code interpreter tool call item. + - `Float = Float` - - `output_index: Integer` + - `UnionMember2 = bool` - The index of the output item in the response for which the code interpreter call is completed. + - `UnionMember3 = Array[String | Float]` - - `sequence_number: Integer` + - `String = String` - The sequence number of this event, used to order streaming events. + - `Float = Float` - - `type: :"response.code_interpreter_call.completed"` + - `UnionMember1 = untyped` - The type of the event. Always `response.code_interpreter_call.completed`. + - `type: :and | :or` - - `:"response.code_interpreter_call.completed"` + Type of operation: `and` or `or`. - - `agent: Agent{ agent_name}` + - `:and` - The agent that owns this multi-agent streaming event. + - `:or` - - `agent_name: String` + - `max_num_results: Integer` - The canonical name of the agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. -### Beta Response Code Interpreter Call In Progress Event + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` -- `class BetaResponseCodeInterpreterCallInProgressEvent` + Ranking options for search. - Emitted when a code interpreter call is in progress. + - `hybrid_search: HybridSearch{ 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 unique identifier of the code interpreter tool call item. + - `embedding_weight: Float` - - `output_index: Integer` + The weight of the embedding in the reciprocal ranking fusion. - The index of the output item in the response for which the code interpreter call is in progress. + - `text_weight: Float` - - `sequence_number: Integer` + The weight of the text in the reciprocal ranking fusion. - The sequence number of this event, used to order streaming events. + - `ranker: :auto | :"default-2024-11-15"` - - `type: :"response.code_interpreter_call.in_progress"` + The ranker to use for the file search. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `:auto` - - `:"response.code_interpreter_call.in_progress"` + - `:"default-2024-11-15"` - - `agent: Agent{ agent_name}` + - `score_threshold: Float` - The agent that owns this multi-agent streaming event. + 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` + - `class BetaComputerTool` - 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). -### Beta Response Code Interpreter Call Interpreting Event + - `type: :computer` -- `class BetaResponseCodeInterpreterCallInterpretingEvent` + The type of the computer tool. Always `computer`. - Emitted when the code interpreter is actively interpreting the code snippet. + - `:computer` - - `item_id: String` + - `class BetaComputerUsePreviewTool` - The unique identifier of the code interpreter tool call item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output_index: Integer` + - `display_height: Integer` - The index of the output item in the response for which the code interpreter is interpreting code. + The height of the computer display. - - `sequence_number: Integer` + - `display_width: Integer` - The sequence number of this event, used to order streaming events. + The width of the computer display. - - `type: :"response.code_interpreter_call.interpreting"` + - `environment: :windows | :mac | :linux | 2 more` - The type of the event. Always `response.code_interpreter_call.interpreting`. + The type of computer environment to control. - - `:"response.code_interpreter_call.interpreting"` + - `:windows` - - `agent: Agent{ agent_name}` + - `:mac` - The agent that owns this multi-agent streaming event. + - `:linux` - - `agent_name: String` + - `:ubuntu` - The canonical name of the agent that produced this item. + - `:browser` -### Beta Response Code Interpreter Tool Call + - `type: :computer_use_preview` -- `class BetaResponseCodeInterpreterToolCall` + The type of the computer use tool. Always `computer_use_preview`. - A tool call to run code. + - `:computer_use_preview` - - `id: String` + - `class BetaWebSearchTool` - The unique ID of the code interpreter 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). - - `code: String` + - `type: :web_search | :web_search_2025_08_26` - The code to run, or null if not available. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `container_id: String` + - `:web_search` - The ID of the container used to run the code. + - `:web_search_2025_08_26` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `filters: Filters{ allowed_domains}` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Filters for the search. - - `class Logs` + - `allowed_domains: Array[String]` - The logs output from the code interpreter. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `logs: String` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The logs output from the code interpreter. + - `search_context_size: :low | :medium | :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. - The type of the output. Always `logs`. + - `:low` - - `:logs` + - `:medium` - - `class Image` + - `:high` - The image output from the code interpreter. + - `user_location: UserLocation{ city, country, region, 2 more}` - - `type: :image` + The approximate location of the user. - The type of the output. Always `image`. + - `city: String` - - `:image` + Free text input for the city of the user, e.g. `San Francisco`. - - `url: String` + - `country: String` - The URL of the image output from the code interpreter. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `region: String` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Free text input for the region of the user, e.g. `California`. - - `:in_progress` + - `timezone: String` - - `:completed` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:incomplete` + - `type: :approximate` - - `:interpreting` + The type of location approximation. Always `approximate`. - - `:failed` + - `:approximate` - - `type: :code_interpreter_call` + - `class Mcp` - The type of the code interpreter tool call. Always `code_interpreter_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). - - `:code_interpreter_call` + - `server_label: String` - - `agent: Agent{ agent_name}` + A label for this MCP server, used to identify it in tool calls. - The agent that produced this item. + - `type: :mcp` - - `agent_name: String` + The type of the MCP tool. Always `mcp`. - The canonical name of the agent that produced this item. + - `:mcp` -### Beta Response Compaction Item + - `allowed_callers: Array[:direct | :programmatic]` -- `class BetaResponseCompactionItem` + The tool invocation context(s). - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `:direct` - - `id: String` + - `:programmatic` - The unique ID of the compaction item. + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `encrypted_content: String` + List of allowed tool names or a filter object. - The encrypted content that was produced by compaction. + - `McpAllowedTools = Array[String]` - - `type: :compaction` + A string array of allowed tool names - The type of the item. Always `compaction`. + - `class McpToolFilter` - - `:compaction` + A filter object to specify which tools are allowed. - - `agent: Agent{ agent_name}` + - `read_only: bool` - 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: Array[String]` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `created_by: String` + - `authorization: String` - The identifier of the actor that created the 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. -### Beta Response Compaction Item Param + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` -- `class BetaResponseCompactionItemParam` + 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 compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Currently supported `connector_id` values are: - - `encrypted_content: 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 encrypted content of the compaction summary. + - `:connector_dropbox` - - `type: :compaction` + - `:connector_gmail` - The type of the item. Always `compaction`. + - `:connector_googlecalendar` - - `:compaction` + - `:connector_googledrive` - - `id: String` + - `:connector_microsoftteams` - The ID of the compaction item. + - `:connector_outlookcalendar` - - `agent: Agent{ agent_name}` + - `:connector_outlookemail` - The agent that produced this item. + - `:connector_sharepoint` - - `agent_name: String` + - `defer_loading: bool` - The canonical name of the agent that produced this item. + Whether this MCP tool is deferred and discovered via tool search. -### Beta Response Completed Event + - `headers: Hash[Symbol, String]` -- `class BetaResponseCompletedEvent` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Emitted when the model response is complete. + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `response: BetaResponse` + Specify which of the MCP server's tools require approval. - Properties of the completed response. + - `class McpToolApprovalFilter` - - `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. - Unique identifier for this Response. + - `always: Always{ read_only, tool_names}` - - `created_at: Float` + A filter object to specify which tools are allowed. - Unix timestamp (in seconds) of when this Response was created. + - `read_only: bool` - - `error: BetaResponseError` + Indicates whether or not a tool modifies data or is read-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 error object returned when the model fails to generate a Response. + - `tool_names: Array[String]` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + List of allowed tool names. - The error code for the response. + - `never: Never{ read_only, tool_names}` - - `:server_error` + A filter object to specify which tools are allowed. - - `:rate_limit_exceeded` + - `read_only: bool` - - `:invalid_prompt` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:bio_policy` + - `tool_names: Array[String]` - - `:vector_store_timeout` + List of allowed tool names. - - `:invalid_image` + - `McpToolApprovalSetting = :always | :never` - - `:invalid_image_format` + 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. - - `:invalid_base64_image` + - `:always` - - `:invalid_image_url` + - `:never` - - `:image_too_large` + - `server_description: String` - - `:image_too_small` + Optional description of the MCP server, used to provide more context. - - `:image_parse_error` + - `server_url: String` - - `:image_content_policy_violation` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:invalid_image_mode` + - `tunnel_id: String` - - `:image_file_too_large` + 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. - - `:unsupported_image_media_type` + - `class CodeInterpreter` - - `:empty_image_file` + A tool that runs Python code to help generate a response to a prompt. - - `:failed_to_download_image` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `:image_file_not_found` + 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` + - `String = String` - A human-readable description of the error. + The container ID. - - `incomplete_details: IncompleteDetails{ reason}` + - `class CodeInterpreterToolAuto` - Details about why the response is incomplete. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `reason: :max_output_tokens | :content_filter` + - `type: :auto` - The reason why the response is incomplete. + Always `auto`. - - `:max_output_tokens` + - `:auto` - - `:content_filter` + - `file_ids: Array[String]` - - `instructions: String | Array[BetaResponseInputItem]` + An optional list of uploaded files to make available to your code. - A system (or developer) message inserted into the model's context. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - 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 memory limit for the code interpreter container. - - `String = String` + - `:"1g"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `:"4g"` - - `InputItemList = Array[BetaResponseInputItem]` + - `:"16g"` - A list of one or many input items to the model, containing - different content types. + - `:"64g"` - - `class BetaEasyInputMessage` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - 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. + Network access policy for the container. - - `content: String | BetaResponseInputMessageContentList` + - `class BetaContainerNetworkPolicyDisabled` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: :disabled` - - `String = String` + Disable outbound network access. Always `disabled`. - A text input to the model. + - `:disabled` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `class BetaContainerNetworkPolicyAllowlist` - A list of one or many input items to the model, containing different content - types. + - `allowed_domains: Array[String]` - - `class BetaResponseInputText` + A list of allowed domains when type is `allowlist`. - A text input to the model. + - `type: :allowlist` - - `text: String` + Allow outbound network access only to specified domains. Always `allowlist`. - The text input to the model. + - `:allowlist` - - `type: :input_text` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - The type of the input item. Always `input_text`. + Optional domain-scoped secrets for allowlisted domains. - - `:input_text` + - `domain: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The domain associated with the secret. - Marks the exact end of a reusable 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 secret to inject for the domain. - The breakpoint mode. Always `explicit`. + - `value: String` - - `:explicit` + The secret value to inject for the domain. - - `class BetaResponseInputImage` + - `type: :code_interpreter` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The type of the code interpreter tool. Always `code_interpreter`. - - `detail: :low | :high | :auto | :original` + - `:code_interpreter` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:low` + The tool invocation context(s). - - `:high` + - `:direct` - - `:auto` + - `:programmatic` - - `:original` + - `class ProgrammaticToolCalling` - - `type: :input_image` + - `type: :programmatic_tool_calling` - The type of the input item. Always `input_image`. + The type of the tool. Always `programmatic_tool_calling`. - - `:input_image` + - `:programmatic_tool_calling` - - `file_id: String` + - `class ImageGeneration` - The ID of the file to be sent to the model. + A tool that generates images using the GPT image models. - - `image_url: String` + - `type: :image_generation` - 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 image generation tool. Always `image_generation`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:image_generation` - Marks the exact end of a reusable 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: :generate | :edit | :auto` - - `mode: :explicit` + Whether to generate a new image or edit an existing image. Default: `auto`. - The breakpoint mode. Always `explicit`. + - `:generate` - - `:explicit` + - `:edit` - - `class BetaResponseInputFile` + - `:auto` - A file input to the model. + - `background: :transparent | :opaque | :auto` - - `type: :input_file` + 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 type of the input item. Always `input_file`. + `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. - - `:input_file` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `detail: :auto | :low | :high` + - `:transparent` - 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`. + - `:opaque` - `:auto` - - `:low` + - `input_fidelity: :high | :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: String` + - `:low` - The content of the file to be sent to the model. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `file_id: String` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The ID of the file to be sent to the model. + - `file_id: String` - - `file_url: String` + File ID for the mask image. - The URL of the file to be sent to the model. + - `image_url: String` - - `filename: String` + Base64-encoded mask image. - The name of the file to be sent to the model. + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The image generation model to use. Default: `gpt-image-1`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String = String` - - `mode: :explicit` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - The breakpoint mode. Always `explicit`. + The image generation model to use. Default: `gpt-image-1`. - - `:explicit` + - `:"gpt-image-1"` - - `role: :user | :assistant | :system | :developer` + - `:"gpt-image-1-mini"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `:"gpt-image-2"` - - `:user` + - `:"gpt-image-2-2026-04-21"` - - `:assistant` + - `:"gpt-image-1.5"` - - `:system` + - `:"chatgpt-image-latest"` - - `:developer` + - `moderation: :auto | :low` - - `phase: :commentary` + Moderation level for the generated image. Default: `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` + - `:low` - - `type: :message` + - `output_compression: Integer` - The type of the message input. Always `message`. + Compression level for the output image. Default: 100. - - `:message` + - `output_format: :png | :webp | :jpeg` - - `class Message` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - 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. + - `:png` - - `content: BetaResponseInputMessageContentList` + - `:webp` - A list of one or many input items to the model, containing different content - types. + - `:jpeg` - - `role: :user | :system | :developer` + - `partial_images: Integer` - The role of the message input. One of `user`, `system`, or `developer`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `:user` + - `quality: :low | :medium | :high | :auto` - - `:system` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `:developer` + - `:low` - - `agent: Agent{ 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: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `status: :in_progress | :completed | :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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `String = String` - - `:in_progress` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `:completed` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `:incomplete` + - `:"1024x1024"` - - `type: :message` + - `:"1024x1536"` - The type of the message input. Always set to `message`. + - `:"1536x1024"` - - `:message` + - `:auto` - - `class BetaResponseOutputMessage` + - `class LocalShell` - An output message from the model. + A tool that allows the model to execute shell commands in a local environment. - - `id: String` + - `type: :local_shell` - The unique ID of the output message. + The type of the local shell tool. Always `local_shell`. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `:local_shell` - The content of the output message. + - `class BetaFunctionShellTool` - - `class BetaResponseOutputText` + A tool that allows the model to execute shell commands. - A text output from the model. + - `type: :shell` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The type of the shell tool. Always `shell`. - The annotations of the text output. + - `:shell` - - `class FileCitation` + - `allowed_callers: Array[:direct | :programmatic]` - A citation to a file. + The tool invocation context(s). - - `file_id: String` + - `:direct` - The ID of the file. + - `:programmatic` - - `filename: String` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - The filename of the file cited. + - `class BetaContainerAuto` - - `index: Integer` + - `type: :container_auto` - The index of the file in the list of files. + Automatically creates a container for this request - - `type: :file_citation` + - `:container_auto` - The type of the file citation. Always `file_citation`. + - `file_ids: Array[String]` - - `:file_citation` + An optional list of uploaded files to make available to your code. - - `class URLCitation` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - A citation for a web resource used to generate a model response. + The memory limit for the container. - - `end_index: Integer` + - `:"1g"` - The index of the last character of the URL citation in the message. + - `:"4g"` - - `start_index: Integer` + - `:"16g"` - The index of the first character of the URL citation in the message. + - `:"64g"` - - `title: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The title of the web resource. + Network access policy for the container. - - `type: :url_citation` + - `class BetaContainerNetworkPolicyDisabled` - The type of the URL citation. Always `url_citation`. + - `class BetaContainerNetworkPolicyAllowlist` - - `:url_citation` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `url: String` + An optional list of skills referenced by id or inline data. - The URL of the web resource. + - `class BetaSkillReference` - - `class ContainerFileCitation` + - `skill_id: String` - A citation for a container file used to generate a model response. + The ID of the referenced skill. - - `container_id: String` + - `type: :skill_reference` - The ID of the container file. + References a skill created with the /v1/skills endpoint. - - `end_index: Integer` + - `:skill_reference` - The index of the last character of the container file citation in the message. + - `version: String` - - `file_id: String` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The ID of the file. + - `class BetaInlineSkill` - - `filename: String` + - `description: String` - The filename of the container file cited. + The description of the skill. - - `start_index: Integer` + - `name: String` - The index of the first character of the container file citation in the message. + The name of the skill. - - `type: :container_file_citation` + - `source: BetaInlineSkillSource` - The type of the container file citation. Always `container_file_citation`. + Inline skill payload - - `:container_file_citation` + - `data: String` - - `class FilePath` + Base64-encoded skill zip bundle. - A path to a file. + - `media_type: :"application/zip"` - - `file_id: String` + The media type of the inline skill payload. Must be `application/zip`. - The ID of the file. + - `:"application/zip"` - - `index: Integer` + - `type: :base64` - The index of the file in the list of files. + The type of the inline skill source. Must be `base64`. - - `type: :file_path` + - `:base64` - The type of the file path. Always `file_path`. + - `type: :inline` - - `:file_path` + Defines an inline skill for this request. - - `text: String` + - `:inline` - The text output from the model. + - `class BetaLocalEnvironment` - - `type: :output_text` + - `type: :local` - The type of the output text. Always `output_text`. + Use a local computer environment. - - `:output_text` + - `:local` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `skills: Array[BetaLocalSkill]` - - `token: String` + An optional list of skills. - - `bytes: Array[Integer]` + - `description: String` - - `logprob: Float` + The description of the skill. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `name: String` - - `token: String` + The name of the skill. - - `bytes: Array[Integer]` + - `path: String` - - `logprob: Float` + The path to the directory containing the skill. - - `class BetaResponseOutputRefusal` + - `class BetaContainerReference` - A refusal from the model. + - `container_id: String` - - `refusal: String` + The ID of the referenced container. - The refusal explanation from the model. + - `type: :container_reference` - - `type: :refusal` + References a container created with the /v1/containers endpoint - The type of the refusal. Always `refusal`. + - `:container_reference` - - `:refusal` + - `class BetaCustomTool` - - `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 | :completed | :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: Array[:direct | :programmatic]` - - `:incomplete` + The tool invocation context(s). - - `type: :message` + - `:direct` - The type of the output message. Always `message`. + - `:programmatic` - - `:message` + - `defer_loading: bool` - - `agent: Agent{ agent_name}` + Whether this tool should be deferred and discovered via tool search. - The agent that produced this item. + - `description: 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_: Text{ type} | Grammar{ definition, syntax, type}` - - `phase: :commentary` + 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. + - `class Text` - - `:commentary` + Unconstrained free-form text. - - `class BetaResponseFileSearchToolCall` + - `type: :text` - 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. + Unconstrained text format. Always `text`. - - `id: String` + - `:text` - The unique ID of the file search tool call. + - `class Grammar` - - `queries: Array[String]` + A grammar defined by the user. - The queries used to search for files. + - `definition: String` - - `status: :in_progress | :searching | :completed | 2 more` + The grammar definition. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `syntax: :lark | :regex` - - `:in_progress` + The syntax of the grammar definition. One of `lark` or `regex`. - - `:searching` + - `:lark` - - `:completed` + - `:regex` - - `:incomplete` + - `type: :grammar` - - `:failed` + Grammar format. Always `grammar`. - - `type: :file_search_call` + - `:grammar` - The type of the file search tool call. Always `file_search_call`. + - `class BetaNamespaceTool` - - `:file_search_call` + Groups function/custom tools under a shared namespace. - - `agent: Agent{ agent_name}` + - `description: String` - The agent that produced this item. + A description of the namespace shown to the model. - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - The results of the file search tool call. + The function/custom tools available inside this namespace. - - `attributes: Hash[Symbol, String | Float | bool]` + - `class Function` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `name: String` - - `String = String` + - `type: :function` - - `Float = Float` + - `:function` - - `UnionMember2 = bool` + - `allowed_callers: Array[:direct | :programmatic]` - - `file_id: String` + The tool invocation context(s). - The unique ID of the file. + - `:direct` - - `filename: String` + - `:programmatic` - The name of the file. + - `defer_loading: bool` - - `score: Float` + Whether this function should be deferred and discovered via tool search. - The relevance score of the file - a value between 0 and 1. + - `description: String` - - `text: String` + - `output_schema: Hash[Symbol, untyped]` - The text that was retrieved from the file. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class BetaResponseComputerToolCall` + - `parameters: untyped` - 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. + - `strict: bool` - - `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 computer call. + - `class BetaCustomTool` - - `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) - An identifier used when responding to the tool call with output. + - `type: :namespace` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + The type of the tool. Always `namespace`. - The pending safety checks for the computer call. + - `:namespace` - - `id: String` + - `class BetaToolSearchTool` - The ID of the pending safety check. + Hosted or BYOT tool search configuration for deferred tools. - - `code: String` + - `type: :tool_search` - The type of the pending safety check. + The type of the tool. Always `tool_search`. - - `message: String` + - `:tool_search` - Details about the pending safety check. + - `description: String` - - `status: :in_progress | :completed | :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: :server | :client` - - `:in_progress` + Whether tool search is executed by the server or by the client. - - `:completed` + - `:server` - - `:incomplete` + - `:client` - - `type: :computer_call` + - `parameters: untyped` - The type of the computer call. Always `computer_call`. + Parameter schema for a client-executed tool search tool. - - `:computer_call` + - `class BetaWebSearchPreviewTool` - - `action: 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 | :web_search_preview_2025_03_11` - - `class Click` + 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 | :right | :wheel | 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: Array[:text | :image]` - - `:left` + - `:text` - - `:right` + - `:image` - - `:wheel` + - `search_context_size: :low | :medium | :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: UserLocation{ type, city, country, 2 more}` - - `x: Integer` + The user's location. - The x-coordinate where the click occurred. + - `type: :approximate` - - `y_: Integer` + The type of location approximation. Always `approximate`. - The y-coordinate where the click occurred. + - `:approximate` - - `keys: Array[String]` + - `city: String` - The keys being held while clicking. + Free text input for the city of the user, e.g. `San Francisco`. - - `class DoubleClick` + - `country: 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[String]` + - `region: String` - The keys being held while double-clicking. + Free text input for the region of the user, e.g. `California`. - - `type: :double_click` + - `timezone: 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` + - `class BetaApplyPatchTool` - - `x: Integer` + Allows the assistant to create, delete, or update files using unified diffs. - The x-coordinate where the double click occurred. + - `type: :apply_patch` - - `y_: Integer` + The type of the tool. Always `apply_patch`. - The y-coordinate where the double click occurred. + - `:apply_patch` - - `class Drag` + - `allowed_callers: Array[:direct | :programmatic]` - A drag action. + The tool invocation context(s). - - `path: Array[Path{ 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 } - ] - ``` + - `type: :tool_search_output` - - `x: Integer` + The item type. Always `tool_search_output`. - The x-coordinate. + - `:tool_search_output` - - `y_: Integer` + - `id: String` - The y-coordinate. + The unique ID of this tool search output. - - `type: :drag` + - `agent: Agent{ agent_name}` - Specifies the event type. For a drag action, this property is always set to `drag`. + The agent that produced this item. - - `:drag` + - `agent_name: String` - - `keys: Array[String]` + The canonical name of the agent that produced this item. - The keys being held while dragging the mouse. + - `call_id: String` - - `class Keypress` + The unique ID of the tool search call generated by the model. - A collection of keypresses the model would like to perform. + - `execution: :server | :client` - - `keys: Array[String]` + Whether tool search was executed by the server or by the client. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `:server` - - `type: :keypress` + - `:client` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `status: :in_progress | :completed | :incomplete` - - `:keypress` + The status of the tool search output. - - `class Move` + - `:in_progress` - A mouse move action. + - `:completed` - - `type: :move` + - `:incomplete` - Specifies the event type. For a move action, this property is always set to `move`. + - `class AdditionalTools` - - `:move` + - `role: :developer` - - `x: Integer` + The role that provided the additional tools. Only `developer` is supported. - The x-coordinate to move to. + - `:developer` - - `y_: Integer` + - `tools: Array[BetaTool]` - The y-coordinate to move to. + A list of additional tools made available at this item. - - `keys: Array[String]` + - `class BetaFunctionTool` - The keys being held while moving the mouse. + 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). - - `class Screenshot` + - `class BetaFileSearchTool` - A screenshot action. + 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: :screenshot` + - `class BetaComputerTool` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:screenshot` + - `class BetaComputerUsePreviewTool` - - `class Scroll` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A scroll action. + - `class BetaWebSearchTool` - - `scroll_x: Integer` + 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 horizontal scroll distance. + - `class Mcp` - - `scroll_y: Integer` + 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 vertical scroll distance. + - `class CodeInterpreter` - - `type: :scroll` + A tool that runs Python code to help generate a response to a prompt. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `class ProgrammaticToolCalling` - - `:scroll` + - `class ImageGeneration` - - `x: Integer` + A tool that generates images using the GPT image models. - The x-coordinate where the scroll occurred. + - `class LocalShell` - - `y_: Integer` + A tool that allows the model to execute shell commands in a local environment. - The y-coordinate where the scroll occurred. + - `class BetaFunctionShellTool` - - `keys: Array[String]` + A tool that allows the model to execute shell commands. - The keys being held while scrolling. + - `class BetaCustomTool` - - `class 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) - An action to type in text. + - `class BetaNamespaceTool` - - `text: String` + Groups function/custom tools under a shared namespace. - The text to type. + - `class BetaToolSearchTool` - - `type: :type` + Hosted or BYOT tool search configuration for deferred tools. - Specifies the event type. For a type action, this property is always set to `type`. + - `class BetaWebSearchPreviewTool` - - `: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). - - `class Wait` + - `class BetaApplyPatchTool` - A wait action. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: :wait` + - `type: :additional_tools` - Specifies the event type. For a wait action, this property is always set to `wait`. + The item type. Always `additional_tools`. - - `:wait` + - `:additional_tools` - - `actions: BetaComputerActionList` + - `id: String` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The unique ID of this additional tools item. - - `class Click` + - `agent: Agent{ agent_name}` - A click action. + The agent that produced this item. - - `class DoubleClick` + - `agent_name: String` - A double click action. + The canonical name of the agent that produced this item. - - `class Drag` + - `class BetaResponseReasoningItem` - A drag action. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `class Keypress` + - `id: String` - A collection of keypresses the model would like to perform. + The unique identifier of the reasoning content. - - `class Move` + - `summary: Array[Summary{ text, type}]` - A mouse move action. + Reasoning summary content. - - `class Screenshot` + - `text: String` - A screenshot action. + A summary of the reasoning output from the model so far. - - `class Scroll` + - `type: :summary_text` - A scroll action. + The type of the object. Always `summary_text`. - - `class Type` + - `:summary_text` - An action to type in text. + - `type: :reasoning` - - `class Wait` + The type of the object. Always `reasoning`. - A wait action. + - `:reasoning` - `agent: Agent{ agent_name}` @@ -59447,58 +69868,53 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput` - - The output of a computer tool call. - - - `call_id: String` - - The ID of the computer tool call that produced the output. + - `content: Array[Content{ text, type}]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + Reasoning text content. - A computer screenshot image used with the computer use tool. + - `text: String` - - `type: :computer_screenshot` + The reasoning text from the model. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `type: :reasoning_text` - - `:computer_screenshot` + The type of the reasoning text. Always `reasoning_text`. - - `file_id: String` + - `:reasoning_text` - The identifier of an uploaded file that contains the screenshot. + - `encrypted_content: String` - - `image_url: String` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The URL of the screenshot image. + - `status: :in_progress | :completed | :incomplete` - - `type: :computer_call_output` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the computer tool call output. Always `computer_call_output`. + - `:in_progress` - - `:computer_call_output` + - `:completed` - - `id: String` + - `:incomplete` - The ID of the computer tool call output. + - `class BetaResponseCompactionItemParam` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The safety checks reported by the API that have been acknowledged by the developer. + - `encrypted_content: String` - - `id: String` + The encrypted content of the compaction summary. - The ID of the pending safety check. + - `type: :compaction` - - `code: String` + The type of the item. Always `compaction`. - The type of the pending safety check. + - `:compaction` - - `message: String` + - `id: String` - Details about the pending safety check. + The ID of the compaction item. - `agent: Agent{ agent_name}` @@ -59508,111 +69924,112 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `class ImageGenerationCall` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + An image generation request made by the model. - - `:in_progress` + - `id: String` - - `:completed` + The unique ID of the image generation call. - - `:incomplete` + - `result: String` - - `class BetaResponseFunctionWebSearch` + The generated image encoded in base64. - 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. + - `status: :in_progress | :completed | :generating | :failed` - - `id: String` + The status of the image generation call. - The unique ID of the web search tool call. + - `:in_progress` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). + - `:generating` - - `class Search` + - `:failed` - Action type "search" - Performs a web search query. + - `type: :image_generation_call` - - `type: :search` + The type of the image generation call. Always `image_generation_call`. - The action type. + - `:image_generation_call` - - `:search` + - `agent: Agent{ agent_name}` - - `queries: Array[String]` + The agent that produced this item. - The search queries. + - `agent_name: String` - - `query: String` + The canonical name of the agent that produced this item. - The search query. + - `class BetaResponseCodeInterpreterToolCall` - - `sources: Array[Source{ type, url}]` + A tool call to run code. - The sources used in the search. + - `id: String` - - `type: :url` + The unique ID of the code interpreter tool call. - The type of source. Always `url`. + - `code: String` - - `:url` + The code to run, or null if not available. - - `url: String` + - `container_id: String` - The URL of the source. + The ID of the container used to run the code. - - `class OpenPage` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - Action type "open_page" - Opens a specific URL from search results. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: :open_page` + - `class Logs` - The action type. + The logs output from the code interpreter. - - `:open_page` + - `logs: String` - - `url: String` + The logs output from the code interpreter. - The URL opened by the model. + - `type: :logs` - - `class FindInPage` + The type of the output. Always `logs`. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `:logs` - - `pattern: String` + - `class Image` - The pattern or text to search for within the page. + The image output from the code interpreter. - - `type: :find_in_page` + - `type: :image` - The action type. + The type of the output. Always `image`. - - `:find_in_page` + - `: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 | :searching | :completed | :failed` + - `status: :in_progress | :completed | :incomplete | 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: Agent{ agent_name}` @@ -59622,32 +70039,63 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall` + - `class LocalShellCall` - 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 run a command on the local shell. - - `arguments: String` + - `id: String` - A JSON string of the arguments to pass to the function. + The unique ID of the local shell call. + + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` + + The command to run. + + - `env: Hash[Symbol, String]` + + Environment variables to set for the command. + + - `type: :exec` + + The type of the local shell action. Always `exec`. + + - `:exec` + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the command. + + - `user: String` + + Optional user to run the command as. + + - `working_directory: String` + + 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 | :completed | :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: 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: Agent{ agent_name}` @@ -59657,34 +70105,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class LocalShellCallOutput` - The execution context that produced this tool call. + The output of a local shell tool call. - - `class Direct` + - `id: String` - - `type: :direct` + The unique ID of the local shell tool call generated by the model. - - `:direct` + - `output: String` - - `class Program` + 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: Agent{ agent_name}` - - `namespace: 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: :in_progress | :completed | :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` @@ -59692,145 +70141,147 @@ puts(beta_compacted_response) - `:incomplete` - - `class FunctionCallOutput` + - `class ShellCall` - The output of a function tool call. + A tool representing a request to execute one or more shell commands. - - `call_id: String` + - `action: Action{ commands, max_output_length, timeout_ms}` - The unique ID of the function tool call generated by the model. + The shell commands and limits that describe how to run the tool call. - - `output: String | BetaResponseFunctionCallOutputItemList` + - `commands: Array[String]` - Text, image, or file output of the function tool call. + Ordered shell commands for the execution environment to run. - - `String = String` + - `max_output_length: Integer` - A JSON string of the output of the function tool call. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `timeout_ms: Integer` - An array of content outputs (text, image, file) for the function tool call. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `class BetaResponseInputTextContent` + - `call_id: String` - A text input to the model. + The unique ID of the shell tool call generated by the model. - - `text: String` + - `type: :shell_call` - The text input to the model. + The type of the item. Always `shell_call`. - - `type: :input_text` + - `:shell_call` - The type of the input item. Always `input_text`. + - `id: String` - - `:input_text` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - `class BetaResponseInputImageContent` + 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) + - `class Direct` - - `type: :input_image` + - `type: :direct` - The type of the input item. Always `input_image`. + The caller type. Always `direct`. - - `:input_image` + - `:direct` - - `detail: :low | :high | :auto | :original` + - `class Program` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `caller_id: String` - - `:low` + The call ID of the program item that produced this tool call. - - `:high` + - `type: :program` - - `:auto` + The caller type. Always `program`. - - `:original` + - `:program` - - `file_id: String` + - `environment: BetaLocalEnvironment | BetaContainerReference` - The ID of the file to be sent to the model. + The environment to execute the shell commands in. - - `image_url: String` + - `class BetaLocalEnvironment` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class BetaContainerReference` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `status: :in_progress | :completed | :incomplete` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `mode: :explicit` + - `:in_progress` - The breakpoint mode. Always `explicit`. + - `:completed` - - `:explicit` + - `:incomplete` - - `class BetaResponseInputFileContent` + - `class ShellCallOutput` - A file input to the model. + The streamed output items emitted by a shell tool call. - - `type: :input_file` + - `call_id: String` - The type of the input item. Always `input_file`. + The unique ID of the shell tool call generated by the model. - - `:input_file` + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - - `detail: :auto | :low | :high` + Captured chunks of stdout and stderr output, along with their associated outcomes. - 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`. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `:auto` + The exit or timeout outcome associated with this shell call. - - `:low` + - `class Timeout` - - `:high` + Indicates that the shell call exceeded its configured time limit. - - `file_data: String` + - `type: :timeout` - The base64-encoded data of the file to be sent to the model. + The outcome type. Always `timeout`. - - `file_id: String` + - `:timeout` - The ID of the file to be sent to the model. + - `class Exit` - - `file_url: String` + Indicates that the shell commands finished and returned an exit code. - The URL of the file to be sent to the model. + - `exit_code: Integer` - - `filename: String` + The exit code returned by the shell process. - The name of the file to be sent to the model. + - `type: :exit` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The outcome type. Always `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. + - `:exit` - - `mode: :explicit` + - `stderr: String` - The breakpoint mode. Always `explicit`. + Captured stderr output for the shell call. - - `:explicit` + - `stdout: String` - - `type: :function_call_output` + Captured stdout output for the shell call. - The type of the function tool call output. Always `function_call_output`. + - `type: :shell_call_output` - - `:function_call_output` + The type of the item. Always `shell_call_output`. + + - `:shell_call_output` - `id: String` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -59864,9 +70315,13 @@ puts(beta_compacted_response) - `:program` + - `max_output_length: Integer` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + - `status: :in_progress | :completed | :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` @@ -59874,97 +70329,85 @@ puts(beta_compacted_response) - `:incomplete` - - `class AgentMessage` - - A message routed between agents. - - - `author: String` - - The sending agent identity. - - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - Plaintext, image, or encrypted content sent between agents. - - - `class BetaResponseInputTextContent` + - `class ApplyPatchCall` - A text input to the model. + A tool call representing a request to create, delete, or update files using diff patches. - - `class BetaResponseInputImageContent` + - `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 apply patch tool call generated by the model. - - `class EncryptedContent` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The specific create, delete, or update instruction for the apply_patch tool call. - - `encrypted_content: String` + - `class CreateFile` - Opaque encrypted content. + Instruction for creating a new file via the apply_patch tool. - - `type: :encrypted_content` + - `diff: String` - The type of the input item. Always `encrypted_content`. + Unified diff content to apply when creating the file. - - `:encrypted_content` + - `path: String` - - `recipient: String` + Path of the file to create relative to the workspace root. - The destination agent identity. + - `type: :create_file` - - `type: :agent_message` + The operation type. Always `create_file`. - The item type. Always `agent_message`. + - `:create_file` - - `:agent_message` + - `class DeleteFile` - - `id: String` + Instruction for deleting an existing file via the apply_patch tool. - The unique ID of this agent message item. + - `path: String` - - `agent: Agent{ 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` - - `class MultiAgentCall` + - `class UpdateFile` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + Instruction for updating an existing file via the apply_patch tool. - The multi-agent action that was executed. + - `diff: String` - - `:spawn_agent` + Unified diff content to apply to the existing file. - - `:interrupt_agent` + - `path: String` - - `:list_agents` + Path of the file to update relative to the workspace root. - - `:send_message` + - `type: :update_file` - - `:followup_task` + The operation type. Always `update_file`. - - `:wait_agent` + - `:update_file` - - `arguments: String` + - `status: :in_progress | :completed` - The action arguments as a JSON string. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `call_id: String` + - `:in_progress` - The unique ID linking this call to its output. + - `:completed` - - `type: :multi_agent_call` + - `type: :apply_patch_call` - The item type. Always `multi_agent_call`. + The type of the item. Always `apply_patch_call`. - - `:multi_agent_call` + - `:apply_patch_call` - `id: String` - The unique ID of this multi-agent call. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -59974,127 +70417,129 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The execution context that produced this tool call. - The multi-agent action that produced this result. + - `class Direct` - - `:spawn_agent` + - `type: :direct` - - `:interrupt_agent` + The caller type. Always `direct`. - - `:list_agents` + - `:direct` - - `:send_message` + - `class Program` - - `:followup_task` + - `caller_id: String` - - `:wait_agent` + The call ID of the program item that produced this tool call. - - `call_id: String` + - `type: :program` - The unique ID of the multi-agent call. + The caller type. Always `program`. - - `output: Array[Output{ text, type, annotations}]` + - `:program` - Text output returned by the multi-agent action. + - `class ApplyPatchCallOutput` - - `text: String` + The streamed output emitted by an apply patch tool call. - The text content. + - `call_id: String` - - `type: :output_text` + The unique ID of the apply patch tool call generated by the model. - The content type. Always `output_text`. + - `status: :completed | :failed` - - `:output_text` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `:completed` - Citations associated with the text content. + - `:failed` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `type: :apply_patch_call_output` - - `file_id: String` + The type of the item. Always `apply_patch_call_output`. - The ID of the file. + - `:apply_patch_call_output` - - `filename: String` + - `id: String` - The filename of the file cited. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `index: Integer` + - `agent: Agent{ agent_name}` - The index of the file in the list of files. + The agent that produced this item. - - `type: :file_citation` + - `agent_name: String` - The citation type. Always `file_citation`. + The canonical name of the agent that produced this item. - - `:file_citation` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + The execution context that produced this tool call. - - `end_index: Integer` + - `class Direct` - The index of the last character of the citation in the message. + - `type: :direct` - - `start_index: Integer` + The caller type. Always `direct`. - The index of the first character of the citation in the message. + - `:direct` - - `title: String` + - `class Program` - The title of the cited resource. + - `caller_id: String` - - `type: :url_citation` + The call ID of the program item that produced this tool call. - The citation type. Always `url_citation`. + - `type: :program` - - `:url_citation` + The caller type. Always `program`. - - `url: String` + - `:program` - The URL of the cited resource. + - `output: String` - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `container_id: String` + - `class McpListTools` - The ID of the container. + A list of tools available on an MCP server. - - `end_index: Integer` + - `id: String` - The index of the last character of the citation in the message. + The unique ID of the list. - - `file_id: String` + - `server_label: String` - The ID of the container file. + The label of the MCP server. - - `filename: String` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - The filename of the container file cited. + The tools available on the server. - - `start_index: Integer` + - `input_schema: untyped` - The index of the first character of the citation in the message. + The JSON schema describing the tool's input. - - `type: :container_file_citation` + - `name: String` - The citation type. Always `container_file_citation`. + The name of the tool. - - `:container_file_citation` + - `annotations: untyped` - - `type: :multi_agent_call_output` + Additional annotations about the tool. - The item type. Always `multi_agent_call_output`. + - `description: String` - - `:multi_agent_call_output` + The description of the tool. - - `id: String` + - `type: :mcp_list_tools` - The unique ID of this multi-agent call output. + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` - `agent: Agent{ agent_name}` @@ -60104,21 +70549,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall` + - `error: String` - - `arguments: untyped` + Error message if the server could not list tools. - The arguments supplied to the tool search call. + - `class McpApprovalRequest` - - `type: :tool_search_call` + A request for human approval of a tool invocation. - The item type. Always `tool_search_call`. + - `id: String` - - `:tool_search_call` + The unique ID of the approval request. - - `id: String` + - `arguments: String` - The unique ID of this tool search call. + 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: Agent{ agent_name}` @@ -60128,1129 +70587,1106 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` + - `class McpApprovalResponse` - The unique ID of the tool search call generated by the model. + A response to an MCP approval request. - - `execution: :server | :client` + - `approval_request_id: String` - Whether tool search was executed by the server or by the client. + The ID of the approval request being answered. - - `:server` + - `approve: bool` - - `:client` + Whether the request was approved. - - `status: :in_progress | :completed | :incomplete` + - `type: :mcp_approval_response` - The status of the tool search call. + The type of the item. Always `mcp_approval_response`. - - `:in_progress` + - `:mcp_approval_response` - - `:completed` + - `id: String` - - `:incomplete` + The unique ID of the approval response - - `class BetaResponseToolSearchOutputItemParam` + - `agent: Agent{ agent_name}` - - `tools: Array[BetaTool]` + The agent that produced this item. - The loaded tool definitions returned by the tool search output. + - `agent_name: String` - - `class BetaFunctionTool` + 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). + - `reason: String` - - `name: String` + Optional reason for the decision. - The name of the function to call. + - `class McpCall` - - `parameters: Hash[Symbol, untyped]` + An invocation of a tool on an MCP server. - A JSON schema object describing the parameters of the function. + - `id: String` - - `strict: bool` + The unique ID of the tool call. - Whether strict parameter validation is enforced for this function tool. + - `arguments: String` - - `type: :function` + A JSON string of the arguments passed to the tool. - The type of the function tool. Always `function`. + - `name: String` - - `:function` + The name of the tool that was run. - - `allowed_callers: Array[:direct | :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: bool` + - `:mcp_call` - Whether this function is deferred and loaded via tool search. + - `agent: Agent{ agent_name}` - - `description: String` + The agent that produced this item. - A description of the function. Used by the model to determine whether or not to call the function. + - `agent_name: String` - - `output_schema: Hash[Symbol, untyped]` + The canonical name of the agent that produced this item. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `approval_request_id: String` - - `class BetaFileSearchTool` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `error: String` - - `type: :file_search` + The error from the tool call, if any. - The type of the file search tool. Always `file_search`. + - `output: String` - - `:file_search` + The output from the tool call. - - `vector_store_ids: Array[String]` + - `status: :in_progress | :completed | :incomplete | 2 more` - The IDs of the vector stores to search. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `:in_progress` - A filter to apply. + - `:completed` - - `class ComparisonFilter` + - `:incomplete` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `:calling` - - `key: String` + - `:failed` - The key to compare against the value. + - `class BetaResponseCustomToolCallOutput` - - `type: :eq | :ne | :gt | 5 more` + The output of a custom tool call from your code, being sent back to the model. - 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 + The call ID, used to map this custom tool call output to a custom tool call. - - `:eq` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:ne` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `:gt` + - `String = String` - - `:gte` + A string of the output of the custom tool call. - - `:lt` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:lte` + Text, image, or file output of the custom tool call. - - `:in` + - `class BetaResponseInputText` - - `:nin` + A text input to the model. - - `value: String | Float | bool | Array[untyped]` + - `class BetaResponseInputImage` - The value to compare against the attribute key; supports string, number, or boolean types. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `String = String` + - `class BetaResponseInputFile` - - `Float = Float` + A file input to the model. - - `UnionMember2 = bool` + - `type: :custom_tool_call_output` - - `UnionMember3 = Array[untyped]` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `class CompoundFilter` + - `:custom_tool_call_output` - Combine multiple filters using `and` or `or`. + - `id: String` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The unique ID of the custom tool call output in the OpenAI platform. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `agent: Agent{ agent_name}` - - `class ComparisonFilter` + 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_: Direct{ type} | Program{ caller_id, type}` - - `type: :eq | :ne | :gt | 5 more` + The execution context that produced this tool call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class Direct` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `type: :direct` - - `:eq` + The caller type. Always `direct`. - - `:ne` + - `:direct` - - `:gt` + - `class Program` - - `: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 | Float | bool | Array[untyped]` + - `class BetaResponseCustomToolCall` - The value to compare against the attribute key; supports string, number, or boolean types. + A call to a custom tool created by the model. - - `String = String` + - `call_id: String` - - `Float = Float` + An identifier used to map this custom tool call to a tool call output. - - `UnionMember2 = bool` + - `input: String` - - `UnionMember3 = Array[untyped]` + The input for the custom tool call generated by the model. - - `UnionMember1 = untyped` + - `name: String` - - `type: :and | :or` + The name of the custom tool being called. - Type of operation: `and` or `or`. + - `type: :custom_tool_call` - - `:and` + The type of the custom tool call. Always `custom_tool_call`. - - `:or` + - `:custom_tool_call` - - `max_num_results: Integer` + - `id: String` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The unique ID of the custom tool call in the OpenAI platform. - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `agent: Agent{ agent_name}` - Ranking options for search. + The agent that produced this item. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `agent_name: String` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The canonical name of the agent that produced this item. - - `embedding_weight: Float` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The weight of the embedding in the reciprocal ranking fusion. + The execution context that produced this tool call. - - `text_weight: Float` + - `class Direct` - The weight of the text in the reciprocal ranking fusion. + - `type: :direct` - - `ranker: :auto | :"default-2024-11-15"` + - `:direct` - The ranker to use for the file search. + - `class Program` - - `:auto` + - `caller_id: String` - - `:"default-2024-11-15"` + The call ID of the program item that produced this tool call. - - `score_threshold: Float` + - `type: :program` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `:program` - - `class BetaComputerTool` + - `namespace: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The namespace of the custom tool being called. - - `type: :computer` + - `class CompactionTrigger` - The type of the computer tool. Always `computer`. + Compacts the current context. Must be the final input item. - - `:computer` + - `type: :compaction_trigger` - - `class BetaComputerUsePreviewTool` + The type of the item. Always `compaction_trigger`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:compaction_trigger` - - `display_height: Integer` + - `agent: Agent{ agent_name}` - The height of the computer display. + The agent that produced this item. - - `display_width: Integer` + - `agent_name: String` - The width of the computer display. + The canonical name of the agent that produced this item. - - `environment: :windows | :mac | :linux | 2 more` + - `class ItemReference` - The type of computer environment to control. + An internal identifier for an item to reference. - - `:windows` + - `id: String` - - `:mac` + The ID of the item to reference. - - `:linux` + - `agent: Agent{ 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`. + - `type: :item_reference` - - `:computer_use_preview` + The type of item to reference. Always `item_reference`. - - `class BetaWebSearchTool` + - `:item_reference` - 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). + - `class Program` - - `type: :web_search | :web_search_2025_08_26` + - `id: String` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The unique ID of this program item. - - `:web_search` + - `call_id: String` - - `:web_search_2025_08_26` + The stable call ID of the program item. - - `filters: Filters{ allowed_domains}` + - `code: String` - Filters for the search. + The JavaScript source executed by programmatic tool calling. - - `allowed_domains: Array[String]` + - `fingerprint: String` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + Opaque program replay fingerprint that must be round-tripped. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `type: :program` - - `search_context_size: :low | :medium | :high` + The item type. Always `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. + - `:program` - - `:low` + - `agent: Agent{ agent_name}` - - `:medium` + The agent that produced this item. - - `:high` + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` - - `user_location: UserLocation{ city, country, region, 2 more}` + - `id: String` - The approximate location of the user. + The unique ID of this program output item. - - `city: String` + - `call_id: String` - Free text input for the city of the user, e.g. `San Francisco`. + The call ID of the program item. - - `country: String` + - `result: String` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The result produced by the program item. - - `region: String` + - `status: :completed | :incomplete` - Free text input for the region of the user, e.g. `California`. + The terminal status of the program output. - - `timezone: String` + - `:completed` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:incomplete` - - `type: :approximate` + - `type: :program_output` - The type of location approximation. Always `approximate`. + The item type. Always `program_output`. - - `:approximate` + - `:program_output` - - `class Mcp` + - `agent: Agent{ 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` + - `metadata: Hash[Symbol, String]` - The type of the MCP tool. Always `mcp`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `:mcp` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `allowed_callers: Array[:direct | :programmatic]` + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - The tool invocation context(s). + 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. - - `:direct` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - - `:programmatic` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `:"gpt-5.6-sol"` - List of allowed tool names or a filter object. + - `:"gpt-5.6-terra"` - - `McpAllowedTools = Array[String]` + - `:"gpt-5.6-luna"` - A string array of allowed tool names + - `:"gpt-5.4"` - - `class McpToolFilter` + - `:"gpt-5.4-mini"` - A filter object to specify which tools are allowed. + - `:"gpt-5.4-nano"` - - `read_only: bool` + - `:"gpt-5.4-mini-2026-03-17"` - Indicates whether or not a tool modifies data or is read-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.4-nano-2026-03-17"` - - `tool_names: Array[String]` + - `:"gpt-5.3-chat-latest"` - List of allowed tool names. + - `:"gpt-5.2"` - - `authorization: String` + - `:"gpt-5.2-2025-12-11"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `:"gpt-5.2-chat-latest"` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:"gpt-5.2-pro"` - 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.2-pro-2025-12-11"` - Currently supported `connector_id` values are: + - `:"gpt-5.1"` - - 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.1-2025-11-13"` - - `:connector_dropbox` + - `:"gpt-5.1-codex"` - - `:connector_gmail` + - `:"gpt-5.1-mini"` - - `:connector_googlecalendar` + - `:"gpt-5.1-chat-latest"` - - `:connector_googledrive` + - `:"gpt-5"` - - `:connector_microsoftteams` + - `:"gpt-5-mini"` - - `:connector_outlookcalendar` + - `:"gpt-5-nano"` - - `:connector_outlookemail` + - `:"gpt-5-2025-08-07"` - - `:connector_sharepoint` + - `:"gpt-5-mini-2025-08-07"` - - `defer_loading: bool` + - `:"gpt-5-nano-2025-08-07"` - Whether this MCP tool is deferred and discovered via tool search. + - `:"gpt-5-chat-latest"` - - `headers: Hash[Symbol, String]` + - `:"gpt-4.1"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `:"gpt-4.1-mini"` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:"gpt-4.1-nano"` - Specify which of the MCP server's tools require approval. + - `:"gpt-4.1-2025-04-14"` - - `class McpToolApprovalFilter` + - `:"gpt-4.1-mini-2025-04-14"` - 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-4.1-nano-2025-04-14"` - - `always: Always{ read_only, tool_names}` + - `:"o4-mini"` - A filter object to specify which tools are allowed. + - `:"o4-mini-2025-04-16"` - - `read_only: bool` + - `:o3` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `:"o3-2025-04-16"` - - `tool_names: Array[String]` + - `:"o3-mini"` - List of allowed tool names. + - `:"o3-mini-2025-01-31"` - - `never: Never{ read_only, tool_names}` + - `:o1` - A filter object to specify which tools are allowed. + - `:"o1-2024-12-17"` - - `read_only: bool` + - `:"o1-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. + - `:"o1-preview-2024-09-12"` - - `tool_names: Array[String]` + - `:"o1-mini"` - List of allowed tool names. + - `:"o1-mini-2024-09-12"` - - `McpToolApprovalSetting = :always | :never` + - `:"gpt-4o"` - 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-2024-11-20"` - - `:always` + - `:"gpt-4o-2024-08-06"` - - `:never` + - `:"gpt-4o-2024-05-13"` - - `server_description: String` + - `:"gpt-4o-audio-preview"` - Optional description of the MCP server, used to provide more context. + - `:"gpt-4o-audio-preview-2024-10-01"` - - `server_url: String` + - `:"gpt-4o-audio-preview-2024-12-17"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:"gpt-4o-audio-preview-2025-06-03"` - - `tunnel_id: String` + - `:"gpt-4o-mini-audio-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. + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - - `class CodeInterpreter` + - `:"gpt-4o-search-preview"` - A tool that runs Python code to help generate a response to a prompt. + - `:"gpt-4o-mini-search-preview"` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `:"gpt-4o-search-preview-2025-03-11"` - 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-mini-search-preview-2025-03-11"` - - `String = String` + - `:"chatgpt-4o-latest"` - The container ID. + - `:"codex-mini-latest"` - - `class CodeInterpreterToolAuto` + - `:"gpt-4o-mini"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `:"gpt-4o-mini-2024-07-18"` - - `type: :auto` + - `:"gpt-4-turbo"` - Always `auto`. + - `:"gpt-4-turbo-2024-04-09"` - - `:auto` + - `:"gpt-4-0125-preview"` - - `file_ids: Array[String]` + - `:"gpt-4-turbo-preview"` - An optional list of uploaded files to make available to your code. + - `:"gpt-4-1106-preview"` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:"gpt-4-vision-preview"` - The memory limit for the code interpreter container. + - `:"gpt-4"` - - `:"1g"` + - `:"gpt-4-0314"` - - `:"4g"` + - `:"gpt-4-0613"` - - `:"16g"` + - `:"gpt-4-32k"` - - `:"64g"` + - `:"gpt-4-32k-0314"` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:"gpt-4-32k-0613"` - Network access policy for the container. + - `:"gpt-3.5-turbo"` - - `class BetaContainerNetworkPolicyDisabled` + - `:"gpt-3.5-turbo-16k"` - - `type: :disabled` + - `:"gpt-3.5-turbo-0301"` - Disable outbound network access. Always `disabled`. + - `:"gpt-3.5-turbo-0613"` - - `:disabled` + - `:"gpt-3.5-turbo-1106"` - - `class BetaContainerNetworkPolicyAllowlist` + - `:"gpt-3.5-turbo-0125"` - - `allowed_domains: Array[String]` + - `:"gpt-3.5-turbo-16k-0613"` - A list of allowed domains when type is `allowlist`. + - `:"o1-pro"` - - `type: :allowlist` + - `:"o1-pro-2025-03-19"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `:"o3-pro"` - - `:allowlist` + - `:"o3-pro-2025-06-10"` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `:"o3-deep-research"` - Optional domain-scoped secrets for allowlisted domains. + - `:"o3-deep-research-2025-06-26"` - - `domain: String` + - `:"o4-mini-deep-research"` - The domain associated with the secret. + - `:"o4-mini-deep-research-2025-06-26"` - - `name: String` + - `:"computer-use-preview"` - The name of the secret to inject for the domain. + - `:"computer-use-preview-2025-03-11"` - - `value: String` + - `:"gpt-5-codex"` - The secret value to inject for the domain. + - `:"gpt-5-pro"` - - `type: :code_interpreter` + - `:"gpt-5-pro-2025-10-06"` - The type of the code interpreter tool. Always `code_interpreter`. + - `:"gpt-5.1-codex-max"` - - `:code_interpreter` + - `String = String` - - `allowed_callers: Array[:direct | :programmatic]` + - `object: :response` - The tool invocation context(s). + The object type of this resource - always set to `response`. - - `:direct` + - `:response` - - `:programmatic` + - `output: Array[BetaResponseOutputItem]` - - `class ProgrammaticToolCalling` + An array of content items generated by the model. - - `type: :programmatic_tool_calling` + - 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 tool. Always `programmatic_tool_calling`. + - `class BetaResponseOutputMessage` - - `:programmatic_tool_calling` + An output message from the model. - - `class ImageGeneration` + - `class BetaResponseFileSearchToolCall` - A tool that generates images using the GPT image models. + 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_generation` + - `class BetaResponseFunctionToolCall` - The type of the image generation tool. Always `image_generation`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:image_generation` + - `class BetaResponseFunctionToolCallOutputItem` - - `action: :generate | :edit | :auto` + - `id: String` - Whether to generate a new image or edit an existing image. Default: `auto`. + The unique ID of the function call tool output. - - `:generate` + - `call_id: String` - - `:edit` + The unique ID of the function tool call generated by the model. - - `:auto` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `background: :transparent | :opaque | :auto` + The output from the function call generated by your code. + Can be a string or an list of output 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. + - `String = 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. + A string of the output of the function call. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:transparent` + Text, image, or file output of the function call. - - `:opaque` + - `class BetaResponseInputText` - - `:auto` + A text input to the model. - - `input_fidelity: :high | :low` + - `class BetaResponseInputImage` - 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`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:high` + - `class BetaResponseInputFile` - - `:low` + A file input to the model. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `status: :in_progress | :completed | :incomplete` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `file_id: String` + - `:in_progress` - File ID for the mask image. + - `:completed` - - `image_url: String` + - `:incomplete` - Base64-encoded mask image. + - `type: :function_call_output` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The type of the function tool call output. Always `function_call_output`. - The image generation model to use. Default: `gpt-image-1`. + - `:function_call_output` - - `String = String` + - `agent: Agent{ agent_name}` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `agent_name: String` - - `:"gpt-image-1"` + The canonical name of the agent that produced this item. - - `:"gpt-image-1-mini"` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:"gpt-image-2"` + The execution context that produced this tool call. - - `:"gpt-image-2-2026-04-21"` + - `class Direct` - - `:"gpt-image-1.5"` + - `type: :direct` - - `:"chatgpt-image-latest"` + The caller type. Always `direct`. - - `moderation: :auto | :low` + - `:direct` - Moderation level for the generated image. Default: `auto`. + - `class Program` - - `:auto` + - `caller_id: String` - - `:low` + The call ID of the program item that produced this tool call. - - `output_compression: Integer` + - `type: :program` - Compression level for the output image. Default: 100. + The caller type. Always `program`. - - `output_format: :png | :webp | :jpeg` + - `:program` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `created_by: String` - - `:png` + The identifier of the actor that created the item. - - `:webp` + - `class AgentMessage` - - `:jpeg` + - `id: String` - - `partial_images: Integer` + The unique ID of the agent message. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `author: String` - - `quality: :low | :medium | :high | :auto` + The sending agent identity. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `:low` + Encrypted content sent between agents. - - `:medium` + - `class BetaResponseInputText` - - `:high` + A text input to the model. - - `:auto` + - `class BetaResponseOutputText` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + A text output 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`. + - `class Text` - - `String = String` + A text content. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `text: String` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: :text` - - `:"1024x1024"` + - `:text` - - `:"1024x1536"` + - `class SummaryText` - - `:"1536x1024"` + A summary text from the model. - - `:auto` + - `text: String` - - `class LocalShell` + A summary of the reasoning output from the model so far. - A tool that allows the model to execute shell commands in a local environment. + - `type: :summary_text` - - `type: :local_shell` + The type of the object. Always `summary_text`. - The type of the local shell tool. Always `local_shell`. + - `:summary_text` - - `:local_shell` + - `class ReasoningText` - - `class BetaFunctionShellTool` + Reasoning text from the model. - A tool that allows the model to execute shell commands. + - `text: String` - - `type: :shell` + The reasoning text from the model. - The type of the shell tool. Always `shell`. + - `type: :reasoning_text` - - `:shell` + The type of the reasoning text. Always `reasoning_text`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:reasoning_text` - The tool invocation context(s). + - `class BetaResponseOutputRefusal` - - `:direct` + A refusal from the model. - - `:programmatic` + - `class BetaResponseInputImage` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaContainerAuto` + - `class ComputerScreenshot` - - `type: :container_auto` + A screenshot of a computer. - Automatically creates a container for this request + - `detail: :low | :high | :auto | :original` - - `:container_auto` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `file_ids: Array[String]` + - `:low` - An optional list of uploaded files to make available to your code. + - `:high` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:auto` - The memory limit for the container. + - `:original` - - `:"1g"` + - `file_id: String` - - `:"4g"` + The identifier of an uploaded file that contains the screenshot. - - `:"16g"` + - `image_url: String` - - `:"64g"` + The URL of the screenshot image. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :computer_screenshot` - Network access policy for the container. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `class BetaContainerNetworkPolicyDisabled` + - `:computer_screenshot` - - `class BetaContainerNetworkPolicyAllowlist` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `skills: Array[BetaSkillReference | 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` - - `class BetaSkillReference` + The breakpoint mode. Always `explicit`. - - `skill_id: String` + - `:explicit` - The ID of the referenced skill. + - `class BetaResponseInputFile` - - `type: :skill_reference` + A file input to the model. - References a skill created with the /v1/skills endpoint. + - `class EncryptedContent` - - `:skill_reference` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `version: String` + - `encrypted_content: String` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Opaque encrypted content. - - `class BetaInlineSkill` + - `type: :encrypted_content` - - `description: String` + The type of the input item. Always `encrypted_content`. - The description of the skill. + - `:encrypted_content` - - `name: String` + - `recipient: String` - The name of the skill. + The destination agent identity. - - `source: BetaInlineSkillSource` + - `type: :agent_message` - Inline skill payload + The type of the item. Always `agent_message`. - - `data: String` + - `:agent_message` - Base64-encoded skill zip bundle. + - `agent: Agent{ agent_name}` - - `media_type: :"application/zip"` + The agent that produced this item. - The media type of the inline skill payload. Must be `application/zip`. + - `agent_name: String` - - `:"application/zip"` + The canonical name of the agent that produced this item. - - `type: :base64` + - `class MultiAgentCall` - The type of the inline skill source. Must be `base64`. + - `id: String` - - `:base64` + The unique ID of the multi-agent call item. - - `type: :inline` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - Defines an inline skill for this request. + The multi-agent action to execute. - - `:inline` + - `:spawn_agent` - - `class BetaLocalEnvironment` + - `:interrupt_agent` - - `type: :local` + - `:list_agents` - Use a local computer environment. + - `:send_message` - - `:local` + - `:followup_task` - - `skills: Array[BetaLocalSkill]` + - `:wait_agent` - An optional list of skills. + - `arguments: String` - - `description: String` + The JSON string of arguments generated for the action. - The description of the skill. + - `call_id: String` - - `name: String` + The unique ID linking this call to its output. - The name of the skill. + - `type: :multi_agent_call` - - `path: String` + The type of the multi-agent call. Always `multi_agent_call`. - The path to the directory containing the skill. + - `:multi_agent_call` - - `class BetaContainerReference` + - `agent: Agent{ agent_name}` - - `container_id: String` + The agent that produced this item. - The ID of the referenced container. + - `agent_name: String` - - `type: :container_reference` + The canonical name of the agent that produced this item. - References a container created with the /v1/containers endpoint + - `class MultiAgentCallOutput` - - `:container_reference` + - `id: String` - - `class BetaCustomTool` + The unique ID of the multi-agent call output 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) + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `name: String` + The multi-agent action that produced this result. - The name of the custom tool, used to identify it in tool calls. + - `:spawn_agent` - - `type: :custom` + - `:interrupt_agent` - The type of the custom tool. Always `custom`. + - `:list_agents` - - `:custom` + - `:send_message` - - `allowed_callers: Array[:direct | :programmatic]` + - `:followup_task` - The tool invocation context(s). + - `:wait_agent` - - `:direct` + - `call_id: String` - - `:programmatic` + The unique ID of the multi-agent call. - - `defer_loading: bool` + - `output: Array[BetaResponseOutputText]` - Whether this tool should be deferred and discovered via tool search. + Text output returned by the multi-agent action. - - `description: String` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - Optional description of the custom tool, used to provide more context. + The annotations of the text output. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `text: String` - The input format for the custom tool. Default is unconstrained text. + The text output from the model. - - `class Text` + - `type: :output_text` - Unconstrained free-form text. + The type of the output text. Always `output_text`. - - `type: :text` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - Unconstrained text format. Always `text`. + - `type: :multi_agent_call_output` - - `:text` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `class Grammar` + - `:multi_agent_call_output` - A grammar defined by the user. + - `agent: Agent{ agent_name}` - - `definition: String` + The agent that produced this item. - The grammar definition. + - `agent_name: String` - - `syntax: :lark | :regex` + The canonical name of the agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class BetaResponseFunctionWebSearch` - - `:lark` + 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. - - `:regex` + - `class BetaResponseComputerToolCall` - - `type: :grammar` + 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. - Grammar format. Always `grammar`. + - `class BetaResponseComputerToolCallOutputItem` - - `:grammar` + - `id: String` - - `class BetaNamespaceTool` + The unique ID of the computer call tool output. - Groups function/custom tools under a shared namespace. + - `call_id: String` - - `description: String` + The ID of the computer tool call that produced the output. - A description of the namespace shown to the model. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `name: String` + A computer screenshot image used with the computer use tool. - The namespace name used in tool calls (for example, `crm`). + - `status: :completed | :incomplete | :failed | :in_progress` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + 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` - - `class Function` + - `:incomplete` - - `name: String` + - `:failed` - - `type: :function` + - `:in_progress` - - `:function` + - `type: :computer_call_output` - - `allowed_callers: Array[:direct | :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: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:programmatic` + The safety checks reported by the API that have been acknowledged by the + developer. - - `defer_loading: bool` + - `id: String` - Whether this function should be deferred and discovered via tool search. + The ID of the pending safety check. - - `description: String` + - `code: String` - - `output_schema: Hash[Symbol, untyped]` + 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: String` - - `parameters: untyped` + Details about the pending safety check. - - `strict: bool` + - `agent: Agent{ 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. - - `class BetaCustomTool` + - `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. - - `type: :namespace` + - `created_by: String` - The type of the tool. Always `namespace`. + The identifier of the actor that created the item. - - `:namespace` + - `class BetaResponseReasoningItem` - - `class BetaToolSearchTool` + 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). - Hosted or BYOT tool search configuration for deferred tools. + - `class Program` - - `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: String` + The stable call ID of the program item. - Description shown to the model for a client-executed tool search tool. + - `code: String` - - `execution: :server | :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: untyped` + The type of the item. Always `program`. - Parameter schema for a client-executed tool search tool. + - `:program` - - `class BetaWebSearchPreviewTool` + - `agent: Agent{ 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 | :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` + - `class ProgramOutput` - - `:web_search_preview_2025_03_11` + - `id: String` - - `search_content_types: Array[:text | :image]` + The unique ID of the program output item. - - `:text` + - `call_id: String` - - `:image` + The call ID of the program item. - - `search_context_size: :low | :medium | :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 | :incomplete` - - `:medium` + The terminal status of the program output item. - - `:high` + - `:completed` - - `user_location: UserLocation{ 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: Agent{ agent_name}` - - `city: String` + The agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent_name: String` - - `country: 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`. + - `class BetaResponseToolSearchCall` - - `region: 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: String` + - `arguments: untyped` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Arguments used for the tool search call. - - `class BetaApplyPatchTool` + - `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 | :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: Array[:direct | :programmatic]` + - `:client` - The tool invocation context(s). + - `status: :in_progress | :completed | :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: String` + The type of the item. Always `tool_search_call`. - The unique ID of this tool search output. + - `:tool_search_call` - `agent: Agent{ agent_name}` @@ -61260,6 +71696,16 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` + + - `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. @@ -61274,7 +71720,7 @@ puts(beta_compacted_response) - `status: :in_progress | :completed | :incomplete` - The status of the tool search output. + The status of the tool search output item that was recorded. - `:in_progress` @@ -61282,17 +71728,9 @@ puts(beta_compacted_response) - `:incomplete` - - `class AdditionalTools` - - - `role: :developer` - - The role that provided the additional tools. Only `developer` is supported. - - - `:developer` - - `tools: Array[BetaTool]` - A list of additional tools made available at this item. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool` @@ -61358,15 +71796,11 @@ puts(beta_compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: :additional_tools` - - The item type. Always `additional_tools`. - - - `:additional_tools` + - `type: :tool_search_output` - - `id: String` + The type of the item. Always `tool_search_output`. - The unique ID of this additional tools item. + - `:tool_search_output` - `agent: Agent{ agent_name}` @@ -61376,130 +71810,109 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem` - - 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[Summary{ 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`. + - `created_by: String` - - `:summary_text` + The identifier of the actor that created the item. - - `type: :reasoning` + - `class AdditionalTools` - The type of the object. Always `reasoning`. + - `id: String` - - `:reasoning` + The unique ID of the additional tools item. - - `agent: Agent{ agent_name}` + - `role: :unknown | :user | :assistant | 5 more` - The agent that produced this item. + The role that provided the additional tools. - - `agent_name: String` + - `:unknown` - The canonical name of the agent that produced this item. + - `:user` - - `content: Array[Content{ text, type}]` + - `:assistant` - Reasoning text content. + - `:system` - - `text: String` + - `:critic` - The reasoning text from the model. + - `:discriminator` - - `type: :reasoning_text` + - `:developer` - The type of the reasoning text. Always `reasoning_text`. + - `:tool` - - `:reasoning_text` + - `tools: Array[BetaTool]` - - `encrypted_content: String` + The additional tool definitions made available at this item. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `class BetaFunctionTool` - - `status: :in_progress | :completed | :incomplete` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaFileSearchTool` - - `: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` + - `class BetaComputerTool` - - `:incomplete` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaResponseCompactionItemParam` + - `class BetaComputerUsePreviewTool` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `encrypted_content: String` + - `class BetaWebSearchTool` - The encrypted content of the compaction 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). - - `type: :compaction` + - `class Mcp` - The type of the item. Always `compaction`. + 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). - - `:compaction` + - `class CodeInterpreter` - - `id: String` + A tool that runs Python code to help generate a response to a prompt. - The ID of the compaction item. + - `class ProgrammaticToolCalling` - - `agent: Agent{ agent_name}` + - `class ImageGeneration` - The agent that produced this item. + A tool that generates images using the GPT image models. - - `agent_name: String` + - `class LocalShell` - The canonical name of the agent that produced this item. + A tool that allows the model to execute shell commands in a local environment. - - `class ImageGenerationCall` + - `class BetaFunctionShellTool` - An image generation request made by the model. + A tool that allows the model to execute shell commands. - - `id: String` + - `class BetaCustomTool` - The unique ID of the image generation 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) - - `result: String` + - `class BetaNamespaceTool` - The generated image encoded in base64. + Groups function/custom tools under a shared namespace. - - `status: :in_progress | :completed | :generating | :failed` + - `class BetaToolSearchTool` - The status of the image generation call. + Hosted or BYOT tool search configuration for deferred tools. - - `:in_progress` + - `class BetaWebSearchPreviewTool` - - `:completed` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `:generating` + - `class BetaApplyPatchTool` - - `:failed` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: :image_generation_call` + - `type: :additional_tools` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `additional_tools`. - - `:image_generation_call` + - `:additional_tools` - `agent: Agent{ agent_name}` @@ -61509,74 +71922,65 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` + - `class BetaResponseCompactionItem` - A tool call to run code. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: String` - The unique ID of the code interpreter tool call. - - - `code: String` - - The code to run, or null if not available. - - - `container_id: String` + The unique ID of the compaction item. - The ID of the container used to run the code. + - `encrypted_content: String` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + The encrypted content that was produced by compaction. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `type: :compaction` - - `class Logs` + The type of the item. Always `compaction`. - The logs output from the code interpreter. + - `:compaction` - - `logs: String` + - `agent: Agent{ agent_name}` - The logs output from the code interpreter. + The agent that produced this item. - - `type: :logs` + - `agent_name: String` - The type of the output. Always `logs`. + The canonical name of the agent that produced this item. - - `:logs` + - `created_by: String` - - `class Image` + The identifier of the actor that created the item. - The image output from the code interpreter. + - `class ImageGenerationCall` - - `type: :image` + An image generation request made by the model. - The type of the output. Always `image`. + - `id: String` - - `:image` + The unique ID of the image generation call. - - `url: String` + - `result: String` - The URL of the image output from the code interpreter. + The generated image encoded in base64. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `status: :in_progress | :completed | :generating | :failed` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the image generation call. - `:in_progress` - `:completed` - - `:incomplete` - - - `:interpreting` + - `:generating` - `:failed` - - `type: :code_interpreter_call` + - `type: :image_generation_call` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the image generation call. Always `image_generation_call`. - - `:code_interpreter_call` + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -61586,6 +71990,10 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. + - `class BetaResponseCodeInterpreterToolCall` + + A tool call to run code. + - `class LocalShellCall` A tool call to run a command on the local shell. @@ -61688,9 +72096,13 @@ puts(beta_compacted_response) - `:incomplete` - - `class ShellCall` + - `class BetaResponseFunctionShellToolCall` - 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: Action{ commands, max_output_length, timeout_ms}` @@ -61698,30 +72110,60 @@ puts(beta_compacted_response) - `commands: Array[String]` - Ordered shell commands for the execution environment to run. - - `max_output_length: Integer` - 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: Integer` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: String` The unique ID of the shell tool call generated by the model. + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment` + + Represents the use of a local environment to perform shell actions. + + - `type: :local` + + The environment type. Always `local`. + + - `:local` + + - `class BetaResponseContainerReference` + + Represents a container created with /v1/containers. + + - `container_id: String` + + - `type: :container_reference` + + The environment type. Always `container_reference`. + + - `:container_reference` + + - `status: :in_progress | :completed | :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: String` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -61738,8 +72180,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -61750,43 +72190,35 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `environment: BetaLocalEnvironment | BetaContainerReference` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment` - - - `class BetaContainerReference` - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: String` - - `:in_progress` + The ID of the entity that created this tool call. - - `:completed` + - `class BetaResponseFunctionShellToolCallOutput` - - `:incomplete` + The output of a shell tool call that was emitted. - - `class ShellCallOutput` + - `id: String` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: String` The unique ID of the shell tool call generated by the model. - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + - `max_output_length: Integer` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + + An array of shell call output contents - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `class Timeout` @@ -61804,7 +72236,7 @@ puts(beta_compacted_response) - `exit_code: Integer` - The exit code returned by the shell process. + Exit code from the shell process. - `type: :exit` @@ -61814,21 +72246,31 @@ puts(beta_compacted_response) - `stderr: String` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: String` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: :shell_call_output` + - `created_by: String` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `:shell_call_output` + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :shell_call_output` + + The type of the shell call output. Always `shell_call_output`. + + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -61846,8 +72288,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -61858,27 +72298,19 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `max_output_length: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call output. + - `created_by: String` - - `:in_progress` + The identifier of the actor that created the item. - - `:completed` + - `class BetaResponseApplyPatchToolCall` - - `:incomplete` + A tool call that applies file diffs by creating, deleting, or updating files. - - `class ApplyPatchCall` + - `id: String` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: String` @@ -61886,55 +72318,55 @@ puts(beta_compacted_response) - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `class CreateFile` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: String` - Unified diff content to apply when creating the file. + Diff to apply. - `path: String` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: :create_file` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `:create_file` - `class DeleteFile` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: String` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: :delete_file` - The operation type. Always `delete_file`. + Delete the specified file. - `:delete_file` - `class UpdateFile` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: String` - Unified diff content to apply to the existing file. + Diff to apply. - `path: String` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: :update_file` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `:update_file` @@ -61952,10 +72384,6 @@ puts(beta_compacted_response) - `:apply_patch_call` - - `id: String` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -61972,8 +72400,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -61984,13 +72410,19 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `class ApplyPatchCallOutput` + - `created_by: String` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + 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` @@ -62010,10 +72442,6 @@ puts(beta_compacted_response) - `:apply_patch_call_output` - - `id: String` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -62030,8 +72458,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -62042,131 +72468,15 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `output: String` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `class McpListTools` - - 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[Tool{ input_schema, name, annotations, description}]` - - The tools available on the server. - - - `input_schema: untyped` - - The JSON schema describing the tool's input. - - - `name: String` - - The name of the tool. - - - `annotations: untyped` - - Additional annotations about the tool. - - - `description: String` - - The description of the tool. - - - `type: :mcp_list_tools` - - The type of the item. Always `mcp_list_tools`. - - - `:mcp_list_tools` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `error: String` - - Error message if the server could not list tools. - - - `class McpApprovalRequest` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class McpApprovalResponse` - - A response to an MCP approval request. - - - `approval_request_id: String` - - The ID of the approval request being answered. - - - `approve: bool` - - Whether the request was approved. - - - `type: :mcp_approval_response` - - The type of the item. Always `mcp_approval_response`. - - - `:mcp_approval_response` - - - `id: String` - - The unique ID of the approval response - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` + - `created_by: String` - The canonical name of the agent that produced this item. + The ID of the entity that created this tool call output. - - `reason: String` + - `output: String` - Optional reason for the decision. + Optional textual output returned by the apply patch tool. - `class McpCall` @@ -62229,48 +72539,43 @@ puts(beta_compacted_response) - `:failed` - - `class BetaResponseCustomToolCallOutput` - - The output of a custom tool call from your code, being sent back to the model. - - - `call_id: String` + - `class McpListTools` - The call ID, used to map this custom tool call output to a custom tool call. + A list of tools available on an MCP server. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `id: String` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The unique ID of the list. - - `String = String` + - `server_label: String` - A string of the output of the custom tool call. + The label of the MCP server. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - Text, image, or file output of the custom tool call. + The tools available on the server. - - `class BetaResponseInputText` + - `input_schema: untyped` - A text input to the model. + The JSON schema describing the tool's input. - - `class BetaResponseInputImage` + - `name: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The name of the tool. - - `class BetaResponseInputFile` + - `annotations: untyped` - A file input to the model. + Additional annotations about the tool. - - `type: :custom_tool_call_output` + - `description: String` - The type of the custom tool call output. Always `custom_tool_call_output`. + The description of the tool. - - `:custom_tool_call_output` + - `type: :mcp_list_tools` - - `id: String` + The type of the item. Always `mcp_list_tools`. - The unique ID of the custom tool call output in the OpenAI platform. + - `:mcp_list_tools` - `agent: Agent{ agent_name}` @@ -62280,55 +72585,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - The caller type. Always `program`. + - `error: String` - - `:program` + Error message if the server could not list tools. - - `class BetaResponseCustomToolCall` + - `class McpApprovalRequest` - A call to a custom tool created by the model. + A request for human approval of a tool invocation. - - `call_id: String` + - `id: String` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the approval request. - - `input: String` + - `arguments: String` - The input for the custom tool call generated by the model. + A JSON string of arguments for the tool. - `name: String` - The name of the custom tool being called. + The name of the tool to 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 making the request. - - `:custom_tool_call` + - `type: :mcp_approval_request` - - `id: String` + The type of the item. Always `mcp_approval_request`. - The unique ID of the custom tool call in the OpenAI platform. + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -62338,39 +72623,27 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - - `:direct` - - - `class Program` - - - `caller_id: String` + - `class McpApprovalResponse` - The call ID of the program item that produced this tool call. + A response to an MCP approval request. - - `type: :program` + - `id: String` - - `:program` + The unique ID of the approval response - - `namespace: String` + - `approval_request_id: String` - The namespace of the custom tool being called. + The ID of the approval request being answered. - - `class CompactionTrigger` + - `approve: bool` - Compacts the current context. Must be the final input item. + Whether the request was approved. - - `type: :compaction_trigger` + - `type: :mcp_approval_response` - The type of the item. Always `compaction_trigger`. + The type of the item. Always `mcp_approval_response`. - - `:compaction_trigger` + - `:mcp_approval_response` - `agent: Agent{ agent_name}` @@ -62380,998 +72653,1104 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ItemReference` + - `reason: String` - An internal identifier for an item to reference. + Optional reason for the decision. - - `id: String` + - `class BetaResponseCustomToolCall` - The ID of the item to reference. + A call to a custom tool created by the model. - - `agent: Agent{ agent_name}` + - `class BetaResponseCustomToolCallOutputItem` - The agent that produced this item. + The output of a custom tool call from your code, being sent back to the model. - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The unique ID of the custom tool call output item. - - `type: :item_reference` + - `status: :in_progress | :completed | :incomplete` - The type of item to reference. Always `item_reference`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:item_reference` + - `:in_progress` - - `class Program` + - `:completed` - - `id: String` + - `:incomplete` - The unique ID of this program item. + - `created_by: String` - - `call_id: String` + The identifier of the actor that created the item. - The stable call ID of the program item. + - `parallel_tool_calls: bool` - - `code: String` + Whether to allow the model to run tool calls in parallel. - The JavaScript source executed by programmatic tool calling. + - `temperature: Float` - - `fingerprint: 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. - Opaque program replay fingerprint that must be round-tripped. + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `type: :program` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The item type. Always `program`. + - `BetaToolChoiceOptions = :none | :auto | :required` - - `:program` + Controls which (if any) tool is called by the model. - - `agent: Agent{ agent_name}` + `none` means the model will not call any tool and instead generates a message. - The agent that produced this item. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `agent_name: String` + `required` means the model must call one or more tools. - The canonical name of the agent that produced this item. + - `:none` - - `class ProgramOutput` + - `:auto` - - `id: String` + - `:required` - The unique ID of this program output item. + - `class BetaToolChoiceAllowed` - - `call_id: String` + Constrains the tools available to the model to a pre-defined set. - The call ID of the program item. + - `mode: :auto | :required` - - `result: String` + Constrains the tools available to the model to a pre-defined set. - The result produced by the program item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `status: :completed | :incomplete` + `required` requires the model to call one or more of the allowed tools. - The terminal status of the program output. + - `:auto` - - `:completed` + - `:required` - - `:incomplete` + - `tools: Array[Hash[Symbol, untyped]]` - - `type: :program_output` + A list of tool definitions that the model should be allowed to call. - The item type. Always `program_output`. + For the Responses API, the list of tool definitions might look like: - - `:program_output` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `agent: Agent{ agent_name}` + - `type: :allowed_tools` - The agent that produced this item. + Allowed tool configuration type. Always `allowed_tools`. - - `agent_name: String` + - `:allowed_tools` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceTypes` - - `metadata: Hash[Symbol, 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). - Set of 16 key-value pairs that can be attached to an object. 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: :file_search | :web_search_preview | :computer | 5 more` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + Allowed values are: - 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. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `:file_search` - 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. + - `:web_search_preview` - - `:"gpt-5.6-sol"` + - `:computer` - - `:"gpt-5.6-terra"` + - `:computer_use_preview` - - `:"gpt-5.6-luna"` + - `:computer_use` - - `:"gpt-5.4"` + - `:web_search_preview_2025_03_11` - - `:"gpt-5.4-mini"` + - `:image_generation` - - `:"gpt-5.4-nano"` + - `:code_interpreter` - - `:"gpt-5.4-mini-2026-03-17"` + - `class BetaToolChoiceFunction` - - `:"gpt-5.4-nano-2026-03-17"` + Use this option to force the model to call a specific function. - - `:"gpt-5.3-chat-latest"` + - `name: String` - - `:"gpt-5.2"` + The name of the function to call. - - `:"gpt-5.2-2025-12-11"` + - `type: :function` - - `:"gpt-5.2-chat-latest"` + For function calling, the type is always `function`. - - `:"gpt-5.2-pro"` + - `:function` - - `:"gpt-5.2-pro-2025-12-11"` + - `class BetaToolChoiceMcp` - - `:"gpt-5.1"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `:"gpt-5.1-2025-11-13"` + - `server_label: String` - - `:"gpt-5.1-codex"` + The label of the MCP server to use. - - `:"gpt-5.1-mini"` + - `type: :mcp` - - `:"gpt-5.1-chat-latest"` + For MCP tools, the type is always `mcp`. - - `:"gpt-5"` + - `:mcp` - - `:"gpt-5-mini"` + - `name: String` - - `:"gpt-5-nano"` + The name of the tool to call on the server. - - `:"gpt-5-2025-08-07"` + - `class BetaToolChoiceCustom` - - `:"gpt-5-mini-2025-08-07"` + Use this option to force the model to call a specific custom tool. - - `:"gpt-5-nano-2025-08-07"` + - `name: String` - - `:"gpt-5-chat-latest"` + The name of the custom tool to call. - - `:"gpt-4.1"` + - `type: :custom` - - `:"gpt-4.1-mini"` + For custom tool calling, the type is always `custom`. - - `:"gpt-4.1-nano"` + - `:custom` - - `:"gpt-4.1-2025-04-14"` + - `class BetaSpecificProgrammaticToolCallingParam` - - `:"gpt-4.1-mini-2025-04-14"` + - `type: :programmatic_tool_calling` - - `:"gpt-4.1-nano-2025-04-14"` + The tool to call. Always `programmatic_tool_calling`. - - `:"o4-mini"` + - `:programmatic_tool_calling` - - `:"o4-mini-2025-04-16"` + - `class BetaToolChoiceApplyPatch` - - `:o3` + Forces the model to call the apply_patch tool when executing a tool call. - - `:"o3-2025-04-16"` + - `type: :apply_patch` - - `:"o3-mini"` + The tool to call. Always `apply_patch`. - - `:"o3-mini-2025-01-31"` + - `:apply_patch` - - `:o1` + - `class BetaToolChoiceShell` - - `:"o1-2024-12-17"` + Forces the model to call the shell tool when a tool call is required. - - `:"o1-preview"` + - `type: :shell` - - `:"o1-preview-2024-09-12"` + The tool to call. Always `shell`. - - `:"o1-mini"` + - `:shell` - - `:"o1-mini-2024-09-12"` + - `tools: Array[BetaTool]` - - `:"gpt-4o"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `:"gpt-4o-2024-11-20"` + We support the following categories of tools: - - `:"gpt-4o-2024-08-06"` + - **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. - - `:"gpt-4o-2024-05-13"` + - `class BetaFunctionTool` - - `:"gpt-4o-audio-preview"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `:"gpt-4o-audio-preview-2024-10-01"` + - `class BetaFileSearchTool` - - `:"gpt-4o-audio-preview-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). - - `:"gpt-4o-audio-preview-2025-06-03"` + - `class BetaComputerTool` - - `:"gpt-4o-mini-audio-preview"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `class BetaComputerUsePreviewTool` - - `:"gpt-4o-search-preview"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:"gpt-4o-mini-search-preview"` + - `class BetaWebSearchTool` - - `:"gpt-4o-search-preview-2025-03-11"` + 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-search-preview-2025-03-11"` + - `class Mcp` - - `:"chatgpt-4o-latest"` + 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). - - `:"codex-mini-latest"` + - `class CodeInterpreter` - - `:"gpt-4o-mini"` + A tool that runs Python code to help generate a response to a prompt. - - `:"gpt-4o-mini-2024-07-18"` + - `class ProgrammaticToolCalling` - - `:"gpt-4-turbo"` + - `class ImageGeneration` - - `:"gpt-4-turbo-2024-04-09"` + A tool that generates images using the GPT image models. - - `:"gpt-4-0125-preview"` + - `class LocalShell` - - `:"gpt-4-turbo-preview"` + A tool that allows the model to execute shell commands in a local environment. - - `:"gpt-4-1106-preview"` + - `class BetaFunctionShellTool` - - `:"gpt-4-vision-preview"` + A tool that allows the model to execute shell commands. - - `:"gpt-4"` + - `class BetaCustomTool` - - `:"gpt-4-0314"` + 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) - - `:"gpt-4-0613"` + - `class BetaNamespaceTool` - - `:"gpt-4-32k"` + Groups function/custom tools under a shared namespace. - - `:"gpt-4-32k-0314"` + - `class BetaToolSearchTool` - - `:"gpt-4-32k-0613"` + Hosted or BYOT tool search configuration for deferred tools. - - `:"gpt-3.5-turbo"` + - `class BetaWebSearchPreviewTool` - - `:"gpt-3.5-turbo-16k"` + 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-3.5-turbo-0301"` + - `class BetaApplyPatchTool` - - `:"gpt-3.5-turbo-0613"` + Allows the assistant to create, delete, or update files using unified diffs. - - `:"gpt-3.5-turbo-1106"` + - `top_p: Float` - - `:"gpt-3.5-turbo-0125"` + 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. - - `:"gpt-3.5-turbo-16k-0613"` + We generally recommend altering this or `temperature` but not both. - - `:"o1-pro"` + - `background: bool` - - `:"o1-pro-2025-03-19"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `:"o3-pro"` + - `completed_at: Float` - - `:"o3-pro-2025-06-10"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `:"o3-deep-research"` + - `conversation: Conversation{ id}` - - `:"o3-deep-research-2025-06-26"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `:"o4-mini-deep-research"` + - `id: String` - - `:"o4-mini-deep-research-2025-06-26"` + The unique ID of the conversation that this response was associated with. - - `:"computer-use-preview"` + - `max_output_tokens: Integer` - - `:"computer-use-preview-2025-03-11"` + 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). - - `:"gpt-5-codex"` + - `max_tool_calls: Integer` - - `:"gpt-5-pro"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `:"gpt-5-pro-2025-10-06"` + - `moderation: Moderation{ input, output}` - - `:"gpt-5.1-codex-max"` + Moderation results for the response input and output, if moderated completions were requested. - - `String = String` + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `object: :response` + Moderation for the response input. - The object type of this resource - always set to `response`. + - `class ModerationResult` - - `:response` + A moderation result produced for the response input or output. - - `output: Array[BetaResponseOutputItem]` + - `categories: Hash[Symbol, bool]` - An array of content items generated by the model. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - 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. + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `class BetaResponseOutputMessage` + Which modalities of input are reflected by the score for each category. - An output message from the model. + - `:text` - - `class BetaResponseFileSearchToolCall` + - `:image` - 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. + - `category_scores: Hash[Symbol, Float]` - - `class BetaResponseFunctionToolCall` + A dictionary of moderation categories to scores. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `flagged: bool` - - `class BetaResponseFunctionToolCallOutputItem` + A boolean indicating whether the content was flagged by any category. - - `id: String` + - `model: String` - The unique ID of the function call tool output. + The moderation model that produced this result. - - `call_id: String` + - `type: :moderation_result` - The unique ID of the function tool call generated by the model. + The object type, which was always `moderation_result` for successful moderation results. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:moderation_result` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `class Error` - - `String = String` + An error produced while attempting moderation for the response input or output. - A string of the output of the function call. + - `code: String` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The error code. - Text, image, or file output of the function call. + - `message: String` - - `class BetaResponseInputText` + The error message. - A text input to the model. + - `type: :error` - - `class BetaResponseInputImage` + The object type, which was always `error` for moderation failures. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:error` - - `class BetaResponseInputFile` + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - A file input to the model. + Moderation for the response output. - - `status: :in_progress | :completed | :incomplete` + - `class ModerationResult` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A moderation result produced for the response input or output. - - `:in_progress` + - `categories: Hash[Symbol, bool]` - - `:completed` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:incomplete` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `type: :function_call_output` + Which modalities of input are reflected by the score for each category. - The type of the function tool call output. Always `function_call_output`. + - `:text` - - `:function_call_output` + - `:image` - - `agent: Agent{ agent_name}` + - `category_scores: Hash[Symbol, Float]` - The agent that produced this item. + A dictionary of moderation categories to scores. - - `agent_name: String` + - `flagged: bool` - The canonical name of the agent that produced this item. + A boolean indicating whether the content was flagged by any category. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `model: String` - The execution context that produced this tool call. + The moderation model that produced this result. - - `class Direct` + - `type: :moderation_result` - - `type: :direct` + The object type, which was always `moderation_result` for successful moderation results. - The caller type. Always `direct`. + - `:moderation_result` - - `:direct` + - `class Error` - - `class Program` + An error produced while attempting moderation for the response input or output. - - `caller_id: String` + - `code: String` - The call ID of the program item that produced this tool call. + The error code. - - `type: :program` + - `message: String` - The caller type. Always `program`. + The error message. - - `:program` + - `type: :error` - - `created_by: String` + The object type, which was always `error` for moderation failures. - The identifier of the actor that created the item. + - `:error` - - `class AgentMessage` + - `previous_response_id: 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 agent message. + - `prompt: BetaResponsePrompt` - - `author: String` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The sending agent identity. + - `id: String` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + The unique identifier of the prompt template to use. - Encrypted content sent between agents. + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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 = String` - `class BetaResponseInputText` A text input to the model. - - `class BetaResponseOutputText` + - `class BetaResponseInputImage` - A text output from the model. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class Text` + - `class BetaResponseInputFile` - A text content. + A file input to the model. - - `text: String` + - `version: String` - - `type: :text` + Optional version of the prompt template. - - `:text` + - `prompt_cache_key: String` - - `class SummaryText` + 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). - A summary text from the model. + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `text: String` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - A summary of the reasoning output from the model so far. + - `mode: :implicit | :explicit` - - `type: :summary_text` + Whether implicit prompt-cache breakpoints were enabled. - The type of the object. Always `summary_text`. + - `:implicit` - - `:summary_text` + - `:explicit` - - `class ReasoningText` + - `ttl: :"30m"` - Reasoning text from the model. + The minimum lifetime applied to each cache breakpoint. - - `text: String` + - `:"30m"` - The reasoning text from the model. + - `prompt_cache_retention: :in_memory | :"24h"` - - `type: :reasoning_text` + Deprecated. Use `prompt_cache_options.ttl` instead. - The type of the reasoning text. Always `reasoning_text`. + 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. - - `:reasoning_text` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `class BetaResponseOutputRefusal` + - 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: Reasoning{ 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: :auto | :current_turn | :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. - A refusal from the model. + - `:auto` - - `class BetaResponseInputImage` + - `:current_turn` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:all_turns` - - `class ComputerScreenshot` + - `effort: :none | :minimal | :low | 4 more` - A screenshot of a computer. + 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. - - `detail: :low | :high | :auto | :original` + - `:none` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:minimal` - `:low` + - `:medium` + - `:high` - - `:auto` + - `:xhigh` - - `:original` + - `:max` - - `file_id: String` + - `generate_summary: :auto | :concise | :detailed` - The identifier of an uploaded file that contains the screenshot. + **Deprecated:** use `summary` instead. - - `image_url: String` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The URL of the screenshot image. + - `:auto` - - `type: :computer_screenshot` + - `:concise` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `:detailed` - - `:computer_screenshot` + - `mode: String | :standard | :pro` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` + - `String = String` - The breakpoint mode. Always `explicit`. + - `Mode = :standard | :pro` - - `:explicit` + Controls the reasoning execution mode for the request. - - `class BetaResponseInputFile` + When returned on a response, this is the effective execution mode. - A file input to the model. + - `:standard` - - `class EncryptedContent` + - `:pro` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `summary: :auto | :concise | :detailed` - - `encrypted_content: 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`. - Opaque encrypted content. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `type: :encrypted_content` + - `:auto` - The type of the input item. Always `encrypted_content`. + - `:concise` - - `:encrypted_content` + - `:detailed` - - `recipient: String` + - `safety_identifier: String` - The destination agent identity. + 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). - - `type: :agent_message` + - `service_tier: :auto | :default | :flex | 2 more` - The type of the item. Always `agent_message`. + Specifies the processing type used for serving the request. - - `:agent_message` + - 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: Agent{ agent_name}` + 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 agent that produced this item. + - `:auto` - - `agent_name: String` + - `:default` - The canonical name of the agent that produced this item. + - `:flex` - - `class MultiAgentCall` + - `:scale` - - `id: String` + - `:priority` - The unique ID of the multi-agent call item. + - `status: BetaResponseStatus` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The multi-agent action to execute. + - `:completed` - - `:spawn_agent` + - `:failed` - - `:interrupt_agent` + - `:in_progress` - - `:list_agents` + - `:cancelled` - - `:send_message` + - `:queued` - - `:followup_task` + - `:incomplete` - - `:wait_agent` + - `text: BetaResponseTextConfig` - - `arguments: String` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The JSON string of arguments generated for the action. + - [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_: BetaResponseFormatTextConfig` - The unique ID linking this call to its output. + An object specifying the format that the model must output. - - `type: :multi_agent_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). - The type of the multi-agent call. Always `multi_agent_call`. + The default format is `{ "type": "text" }` with no additional options. - - `:multi_agent_call` + **Not recommended for gpt-4o and newer models:** - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `class Text` - - `agent_name: String` + Default response format. Used to generate text responses. - The canonical name of the agent that produced this item. + - `type: :text` - - `class MultiAgentCallOutput` + The type of response format being defined. Always `text`. - - `id: String` + - `:text` - The unique ID of the multi-agent call output item. + - `class BetaResponseFormatTextJSONSchemaConfig` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The multi-agent action that produced this result. + - `name: String` - - `:spawn_agent` + 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. - - `:interrupt_agent` + - `schema: Hash[Symbol, untyped]` - - `:list_agents` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:send_message` + - `type: :json_schema` - - `:followup_task` + The type of response format being defined. Always `json_schema`. - - `:wait_agent` + - `:json_schema` - - `call_id: String` + - `description: String` - The unique ID of the multi-agent call. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `output: Array[BetaResponseOutputText]` + - `strict: bool` - Text output returned by the multi-agent action. + 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). - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `class JSONObject` - The annotations of the text 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. - - `text: String` + - `type: :json_object` - The text output from the model. + The type of response format being defined. Always `json_object`. - - `type: :output_text` + - `:json_object` - The type of the output text. Always `output_text`. + - `verbosity: :low | :medium | :high` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + 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: :multi_agent_call_output` + - `:low` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `:medium` - - `:multi_agent_call_output` + - `:high` - - `agent: Agent{ agent_name}` + - `top_logprobs: Integer` - The agent that produced this item. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `agent_name: String` + - `truncation: :auto | :disabled` - The canonical name of the agent that produced this item. + The truncation strategy to use for the model response. - - `class BetaResponseFunctionWebSearch` + - `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 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` - - `class BetaResponseComputerToolCall` + - `:disabled` - 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. + - `usage: BetaResponseUsage` - - `class BetaResponseComputerToolCallOutputItem` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `id: String` + - `input_tokens: Integer` - The unique ID of the computer call tool output. + The number of input tokens. - - `call_id: String` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - The ID of the computer tool call that produced the output. + A detailed breakdown of the input tokens. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `cache_write_tokens: Integer` - A computer screenshot image used with the computer use tool. + The number of input tokens that were written to the cache. - - `status: :completed | :incomplete | :failed | :in_progress` + - `cached_tokens: Integer` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `:completed` + - `output_tokens: Integer` - - `:incomplete` + The number of output tokens. - - `:failed` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - - `:in_progress` + A detailed breakdown of the output tokens. - - `type: :computer_call_output` + - `reasoning_tokens: Integer` - The type of the computer tool call output. Always `computer_call_output`. + The number of reasoning tokens. - - `:computer_call_output` + - `total_tokens: Integer` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + The total number of tokens used. - The safety checks reported by the API that have been acknowledged by the - developer. + - `user: String` - - `id: String` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The ID of the pending safety check. + - `sequence_number: Integer` - - `code: String` + The sequence number of this event. - The type of the pending safety check. + - `type: :"response.in_progress"` - - `message: String` + The type of the event. Always `response.in_progress`. - Details about the pending safety check. + - `:"response.in_progress"` - `agent: Agent{ 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: String` - - The identifier of the actor that created the item. +### Beta Response Includable - - `class BetaResponseReasoningItem` +- `BetaResponseIncludable = :"file_search_call.results" | :"web_search_call.results" | :"web_search_call.action.sources" | 5 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). + Specify additional output data to include in the model response. Currently supported values are: - - `class Program` + - `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). - - `id: String` + - `:"file_search_call.results"` - The unique ID of the program item. + - `:"web_search_call.results"` - - `call_id: String` + - `:"web_search_call.action.sources"` - The stable call ID of the program item. + - `:"message.input_image.image_url"` - - `code: String` + - `:"computer_call_output.output.image_url"` - The JavaScript source executed by programmatic tool calling. + - `:"code_interpreter_call.outputs"` - - `fingerprint: String` + - `:"reasoning.encrypted_content"` - Opaque program replay fingerprint that must be round-tripped. + - `:"message.output_text.logprobs"` - - `type: :program` +### Beta Response Incomplete Event - The type of the item. Always `program`. +- `class BetaResponseIncompleteEvent` - - `:program` + An event that is emitted when a response finishes as incomplete. - - `agent: Agent{ agent_name}` + - `response: BetaResponse` - The agent that produced this item. + The response that was incomplete. - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + Unique identifier for this Response. - - `class ProgramOutput` + - `created_at: Float` - - `id: String` + Unix timestamp (in seconds) of when this Response was created. - The unique ID of the program output item. + - `error: BetaResponseError` - - `call_id: String` + An error object returned when the model fails to generate a Response. - The call ID of the program item. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `result: String` + The error code for the response. - The result produced by the program item. + - `:server_error` - - `status: :completed | :incomplete` + - `:rate_limit_exceeded` - The terminal status of the program output item. + - `:invalid_prompt` - - `:completed` + - `:bio_policy` - - `:incomplete` + - `:vector_store_timeout` - - `type: :program_output` + - `:invalid_image` - The type of the item. Always `program_output`. + - `:invalid_image_format` - - `:program_output` + - `:invalid_base64_image` - - `agent: Agent{ agent_name}` + - `:invalid_image_url` - The agent that produced this item. + - `:image_too_large` - - `agent_name: String` + - `:image_too_small` - The canonical name of the agent that produced this item. + - `:image_parse_error` - - `class BetaResponseToolSearchCall` + - `:image_content_policy_violation` - - `id: String` + - `:invalid_image_mode` - The unique ID of the tool search call item. + - `:image_file_too_large` - - `arguments: untyped` + - `:unsupported_image_media_type` - Arguments used for the tool search call. + - `:empty_image_file` - - `call_id: String` + - `:failed_to_download_image` - The unique ID of the tool search call generated by the model. + - `:image_file_not_found` - - `execution: :server | :client` + - `message: String` - Whether tool search was executed by the server or by the client. + A human-readable description of the error. - - `:server` + - `incomplete_details: IncompleteDetails{ reason}` - - `:client` + Details about why the response is incomplete. - - `status: :in_progress | :completed | :incomplete` + - `reason: :max_output_tokens | :content_filter` - The status of the tool search call item that was recorded. + The reason why the response is incomplete. - - `:in_progress` + - `:max_output_tokens` - - `:completed` + - `:content_filter` - - `:incomplete` + - `instructions: String | Array[BetaResponseInputItem]` - - `type: :tool_search_call` + A system (or developer) message inserted into the model's context. - The type of the item. Always `tool_search_call`. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `:tool_search_call` + - `String = String` - - `agent: Agent{ agent_name}` + A text input to the model, equivalent to a text input with the + `developer` role. - The agent that produced this item. + - `InputItemList = Array[BetaResponseInputItem]` - - `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. + - `class BetaEasyInputMessage` - - `created_by: 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 identifier of the actor that created the item. + - `content: String | BetaResponseInputMessageContentList` - - `class BetaResponseToolSearchOutputItem` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `id: String` + - `String = String` - The unique ID of the tool search output item. + A text input to the model. - - `call_id: String` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - The unique ID of the tool search call generated by the model. + A list of one or many input items to the model, containing different content + types. - - `execution: :server | :client` + - `class BetaResponseInputText` - Whether tool search was executed by the server or by the client. + A text input to the model. - - `:server` + - `text: String` - - `:client` + The text input to the model. - - `status: :in_progress | :completed | :incomplete` + - `type: :input_text` - The status of the tool search output item that was recorded. + The type of the input item. Always `input_text`. - - `:in_progress` + - `:input_text` - - `:completed` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `tools: Array[BetaTool]` + - `mode: :explicit` - The loaded tool definitions returned by tool search. + The breakpoint mode. Always `explicit`. - - `class BetaFunctionTool` + - `:explicit` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaResponseInputImage` - - `class BetaFileSearchTool` + An image input to the model. Learn about [image inputs](https://platform.openai.com/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). + - `detail: :low | :high | :auto | :original` - - `class BetaComputerTool` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:low` - - `class BetaComputerUsePreviewTool` + - `:high` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:auto` - - `class BetaWebSearchTool` + - `:original` - 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: :input_image` - - `class Mcp` + The type of the input item. Always `input_image`. - 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). + - `:input_image` - - `class CodeInterpreter` + - `file_id: String` - A tool that runs Python code to help generate a response to a prompt. + The ID of the file to be sent to the model. - - `class ProgrammaticToolCalling` + - `image_url: String` - - `class ImageGeneration` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - A tool that generates images using the GPT image models. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class LocalShell` + Marks the exact end of a reusable 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 that allows the model to execute shell commands in a local environment. + - `mode: :explicit` - - `class BetaFunctionShellTool` + The breakpoint mode. Always `explicit`. - A tool that allows the model to execute shell commands. + - `:explicit` - - `class BetaCustomTool` + - `class BetaResponseInputFile` - 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 file input to the model. - - `class BetaNamespaceTool` + - `type: :input_file` - Groups function/custom tools under a shared namespace. + The type of the input item. Always `input_file`. - - `class BetaToolSearchTool` + - `:input_file` - Hosted or BYOT tool search configuration for deferred tools. + - `detail: :auto | :low | :high` - - `class BetaWebSearchPreviewTool` + 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`. - 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). + - `:auto` - - `class BetaApplyPatchTool` + - `:low` - Allows the assistant to create, delete, or update files using unified diffs. + - `:high` - - `type: :tool_search_output` + - `file_data: String` - The type of the item. Always `tool_search_output`. + The content of the file to be sent to the model. - - `:tool_search_output` + - `file_id: String` - - `agent: Agent{ agent_name}` + The ID of the file to be sent to the model. - The agent that produced this item. + - `file_url: 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: String` - - `created_by: String` + The name of the file to be sent to the model. - The identifier of the actor that created the item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class AdditionalTools` + Marks the exact end of a reusable 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 additional tools item. + The breakpoint mode. Always `explicit`. - - `role: :unknown | :user | :assistant | 5 more` + - `:explicit` - The role that provided the additional tools. + - `role: :user | :assistant | :system | :developer` - - `:unknown` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - `:user` @@ -63379,251 +73758,248 @@ puts(beta_compacted_response) - `:system` - - `:critic` - - - `:discriminator` - - `:developer` - - `:tool` - - - `tools: Array[BetaTool]` - - The additional tool definitions made available at this item. + - `phase: :commentary | :final_answer` - - `class BetaFunctionTool` + 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. - 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). + - `:commentary` - - `class BetaFileSearchTool` + - `:final_answer` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `type: :message` - - `class BetaComputerTool` + The type of the message input. Always `message`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:message` - - `class BetaComputerUsePreviewTool` + - `class Message` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-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. - - `class BetaWebSearchTool` + - `content: BetaResponseInputMessageContentList` - 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 list of one or many input items to the model, containing different content + types. - - `class Mcp` + - `role: :user | :system | :developer` - 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 role of the message input. One of `user`, `system`, or `developer`. - - `class CodeInterpreter` + - `:user` - A tool that runs Python code to help generate a response to a prompt. + - `:system` - - `class ProgrammaticToolCalling` + - `:developer` - - `class ImageGeneration` + - `agent: Agent{ agent_name}` - A tool that generates images using the GPT image models. + The agent that produced this item. - - `class LocalShell` + - `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. - - `class BetaFunctionShellTool` + - `status: :in_progress | :completed | :incomplete` - A tool that allows the model to execute shell commands. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaCustomTool` + - `: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` - - `class BetaNamespaceTool` + - `:incomplete` - Groups function/custom tools under a shared namespace. + - `type: :message` - - `class BetaToolSearchTool` + The type of the message input. Always set to `message`. - Hosted or BYOT tool search configuration for deferred tools. + - `:message` - - `class BetaWebSearchPreviewTool` + - `class BetaResponseOutputMessage` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + An output message from the model. - - `class BetaApplyPatchTool` + - `id: String` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the output message. - - `type: :additional_tools` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The type of the item. Always `additional_tools`. + The content of the output message. - - `:additional_tools` + - `class BetaResponseOutputText` - - `agent: Agent{ agent_name}` + A text output from the model. - The agent that produced this item. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `agent_name: String` + The annotations of the text output. - The canonical name of the agent that produced this item. + - `class FileCitation` - - `class BetaResponseCompactionItem` + A citation to a file. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `file_id: String` - - `id: String` + The ID of the file. - The unique ID of the compaction item. + - `filename: String` - - `encrypted_content: String` + The filename of the file cited. - The encrypted content that was produced by compaction. + - `index: Integer` - - `type: :compaction` + The index of the file in the list of files. - The type of the item. Always `compaction`. + - `type: :file_citation` - - `:compaction` + The type of the file citation. Always `file_citation`. - - `agent: Agent{ agent_name}` + - `:file_citation` - The agent that produced this item. + - `class URLCitation` - - `agent_name: String` + A citation for a web resource used to generate a model response. - The canonical name of the agent that produced this item. + - `end_index: Integer` - - `created_by: String` + The index of the last character of the URL citation in the message. - The identifier of the actor that created the item. + - `start_index: Integer` - - `class ImageGenerationCall` + The index of the first character of the URL citation in the message. - An image generation request made by the model. + - `title: String` - - `id: String` + The title of the web resource. - The unique ID of the image generation call. + - `type: :url_citation` - - `result: String` + The type of the URL citation. Always `url_citation`. - The generated image encoded in base64. + - `:url_citation` - - `status: :in_progress | :completed | :generating | :failed` + - `url: String` - The status of the image generation call. + The URL of the web resource. - - `:in_progress` + - `class ContainerFileCitation` - - `:completed` + A citation for a container file used to generate a model response. - - `:generating` + - `container_id: String` - - `:failed` + The ID of the container file. - - `type: :image_generation_call` + - `end_index: Integer` - The type of the image generation call. Always `image_generation_call`. + The index of the last character of the container file citation in the message. - - `:image_generation_call` + - `file_id: String` - - `agent: Agent{ agent_name}` + The ID of the file. - The agent that produced this item. + - `filename: String` - - `agent_name: String` + The filename of the container file cited. - The canonical name of the agent that produced this item. + - `start_index: Integer` - - `class BetaResponseCodeInterpreterToolCall` + The index of the first character of the container file citation in the message. - A tool call to run code. + - `type: :container_file_citation` - - `class LocalShellCall` + The type of the container file citation. Always `container_file_citation`. - A tool call to run a command on the local shell. + - `:container_file_citation` - - `id: String` + - `class FilePath` - The unique ID of the local shell call. + A path to a file. - - `action: Action{ command, env, type, 3 more}` + - `file_id: String` - Execute a shell command on the server. + The ID of the file. - - `command: Array[String]` + - `index: Integer` - The command to run. + The index of the file in the list of files. - - `env: Hash[Symbol, String]` + - `type: :file_path` - Environment variables to set for the command. + The type of the file path. Always `file_path`. - - `type: :exec` + - `:file_path` - The type of the local shell action. Always `exec`. + - `text: String` - - `:exec` + The text output from the model. - - `timeout_ms: Integer` + - `type: :output_text` - Optional timeout in milliseconds for the command. + The type of the output text. Always `output_text`. - - `user: String` + - `:output_text` - Optional user to run the command as. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `working_directory: String` + - `token: String` - Optional working directory to run the command in. + - `bytes: Array[Integer]` - - `call_id: String` + - `logprob: Float` - The unique ID of the local shell tool call generated by the model. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `status: :in_progress | :completed | :incomplete` + - `token: String` - The status of the local shell call. + - `bytes: Array[Integer]` - - `:in_progress` + - `logprob: Float` - - `:completed` + - `class BetaResponseOutputRefusal` - - `:incomplete` + A refusal from the model. - - `type: :local_shell_call` + - `refusal: String` - The type of the local shell call. Always `local_shell_call`. + The refusal explanation from the model. - - `:local_shell_call` + - `type: :refusal` - - `agent: Agent{ 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`. - - `class LocalShellCallOutput` + - `:assistant` - The output of a local shell tool call. + - `status: :in_progress | :completed | :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 local shell tool call generated by the model. + - `:in_progress` - - `output: String` + - `:completed` - A JSON string of the output of the local shell tool call. + - `:incomplete` - - `type: :local_shell_call_output` + - `type: :message` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the output message. Always `message`. - - `:local_shell_call_output` + - `:message` - `agent: Agent{ agent_name}` @@ -63633,361 +74009,373 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `phase: :commentary | :final_answer` - - `:in_progress` + 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. - - `:completed` + - `:commentary` - - `:incomplete` + - `:final_answer` - - `class BetaResponseFunctionShellToolCall` + - `class BetaResponseFileSearchToolCall` - A tool call that executes one or more shell commands in a managed environment. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: String` - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `action: Action{ commands, max_output_length, timeout_ms}` + The unique ID of the file search tool call. - The shell commands and limits that describe how to run the tool call. + - `queries: Array[String]` - - `commands: Array[String]` + The queries used to search for files. - - `max_output_length: Integer` + - `status: :in_progress | :searching | :completed | 2 more` - Optional maximum number of characters to return from each command. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `timeout_ms: Integer` + - `:in_progress` - Optional timeout in milliseconds for the commands. + - `:searching` - - `call_id: String` + - `:completed` - The unique ID of the shell tool call generated by the model. + - `:incomplete` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `:failed` - Represents the use of a local environment to perform shell actions. + - `type: :file_search_call` - - `class BetaResponseLocalEnvironment` + The type of the file search tool call. Always `file_search_call`. - Represents the use of a local environment to perform shell actions. + - `:file_search_call` - - `type: :local` + - `agent: Agent{ agent_name}` - The environment type. Always `local`. + The agent that produced this item. - - `:local` + - `agent_name: String` - - `class BetaResponseContainerReference` + The canonical name of the agent that produced this item. - Represents a container created with /v1/containers. + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - `container_id: String` + The results of the file search tool call. - - `type: :container_reference` + - `attributes: Hash[Symbol, String | Float | bool]` - The environment type. Always `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. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `:container_reference` + - `String = String` - - `status: :in_progress | :completed | :incomplete` + - `Float = Float` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `UnionMember2 = bool` - - `:in_progress` + - `file_id: String` - - `:completed` + The unique ID of the file. - - `:incomplete` + - `filename: String` - - `type: :shell_call` + The name of the file. - The type of the item. Always `shell_call`. + - `score: Float` - - `:shell_call` + The relevance score of the file - a value between 0 and 1. - - `agent: Agent{ agent_name}` + - `text: String` - The agent that produced this item. + The text that was retrieved from the file. - - `agent_name: String` + - `class BetaResponseComputerToolCall` - The canonical name of the agent that produced this item. + 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. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `id: String` - The execution context that produced this tool call. + The unique ID of the computer call. - - `class Direct` + - `call_id: String` - - `type: :direct` + An identifier used when responding to the tool call with output. - - `:direct` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `class Program` + 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: String` - - `:program` + The type of the pending safety check. - - `created_by: String` + - `message: String` - The ID of the entity that created this tool call. + Details about the pending safety check. - - `class BetaResponseFunctionShellToolCallOutput` + - `status: :in_progress | :completed | :incomplete` - The output of a shell tool call that was emitted. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: String` + - `:in_progress` - The unique ID of the shell call output. Populated when this item is returned via API. + - `:completed` - - `call_id: String` + - `:incomplete` - The unique ID of the shell tool call generated by the model. + - `type: :computer_call` - - `max_output_length: Integer` + The type of the computer call. Always `computer_call`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `:computer_call` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `action: BetaComputerAction` - An array of shell call output contents + A click action. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `class Click` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + A click action. - - `class Timeout` + - `button: :left | :right | :wheel | 2 more` - Indicates that the shell call exceeded its configured time limit. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: :timeout` + - `:left` - The outcome type. Always `timeout`. + - `:right` - - `:timeout` + - `:wheel` - - `class Exit` + - `:back` - Indicates that the shell commands finished and returned an exit code. + - `:forward` - - `exit_code: Integer` + - `type: :click` - Exit code from the shell process. + Specifies the event type. For a click action, this property is always `click`. - - `type: :exit` + - `:click` - The outcome type. Always `exit`. + - `x: Integer` - - `:exit` + The x-coordinate where the click occurred. - - `stderr: String` + - `y_: Integer` - The standard error output that was captured. + The y-coordinate where the click occurred. - - `stdout: String` + - `keys: Array[String]` - The standard output that was captured. + The keys being held while clicking. - - `created_by: String` + - `class DoubleClick` - The identifier of the actor that created the item. + A double click action. - - `status: :in_progress | :completed | :incomplete` + - `keys: Array[String]` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The keys being held while double-clicking. - - `:in_progress` + - `type: :double_click` - - `:completed` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `:incomplete` + - `:double_click` - - `type: :shell_call_output` + - `x: Integer` - The type of the shell call output. Always `shell_call_output`. + The x-coordinate where the double click occurred. - - `:shell_call_output` + - `y_: Integer` - - `agent: Agent{ agent_name}` + The y-coordinate where the double click occurred. - The agent that produced this item. + - `class Drag` - - `agent_name: String` + A drag action. - The canonical name of the agent that produced this item. + - `path: Array[Path{ x, y_}]` - - `caller_: Direct{ type} | Program{ caller_id, type}` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The execution context that produced this tool call. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `class Direct` + - `x: Integer` - - `type: :direct` + The x-coordinate. - - `:direct` + - `y_: Integer` - - `class Program` + The y-coordinate. - - `caller_id: String` + - `type: :drag` - The call ID of the program item that produced this tool call. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `type: :program` + - `:drag` - - `:program` + - `keys: Array[String]` - - `created_by: String` + The keys being held while dragging the mouse. - The identifier of the actor that created the item. + - `class Keypress` - - `class BetaResponseApplyPatchToolCall` + A collection of keypresses the model would like to perform. - A tool call that applies file diffs by creating, deleting, or updating files. + - `keys: Array[String]` - - `id: String` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: :keypress` - - `call_id: String` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The unique ID of the apply patch tool call generated by the model. + - `:keypress` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `class Move` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + A mouse move action. - - `class CreateFile` + - `type: :move` - Instruction describing how to create a file via the apply_patch tool. + Specifies the event type. For a move action, this property is always set to `move`. - - `diff: String` + - `:move` - Diff to apply. + - `x: Integer` - - `path: String` + The x-coordinate to move to. - Path of the file to create. + - `y_: Integer` - - `type: :create_file` + The y-coordinate to move to. - Create a new file with the provided diff. + - `keys: Array[String]` - - `:create_file` + The keys being held while moving the mouse. - - `class DeleteFile` + - `class Screenshot` - Instruction describing how to delete a file via the apply_patch tool. + A screenshot action. - - `path: String` + - `type: :screenshot` - Path of the file to delete. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: :delete_file` + - `:screenshot` - Delete the specified file. + - `class Scroll` - - `:delete_file` + A scroll action. - - `class UpdateFile` + - `scroll_x: Integer` - Instruction describing how to update a file via the apply_patch tool. + The horizontal scroll distance. - - `diff: String` + - `scroll_y: Integer` - Diff to apply. + The vertical scroll distance. - - `path: String` + - `type: :scroll` - Path of the file to update. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: :update_file` + - `:scroll` - Update an existing file with the provided diff. + - `x: Integer` - - `:update_file` + The x-coordinate where the scroll occurred. - - `status: :in_progress | :completed` + - `y_: Integer` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The y-coordinate where the scroll occurred. - - `:in_progress` + - `keys: Array[String]` - - `:completed` + The keys being held while scrolling. - - `type: :apply_patch_call` + - `class Type` - The type of the item. Always `apply_patch_call`. + An action to type in text. - - `:apply_patch_call` + - `text: String` - - `agent: Agent{ agent_name}` + The text to type. - The agent that produced this item. + - `type: :type` - - `agent_name: String` + Specifies the event type. For a type action, this property is always set to `type`. - The canonical name of the agent that produced this item. + - `:type` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class Wait` - The execution context that produced this tool call. + A wait action. - - `class Direct` + - `type: :wait` - - `type: :direct` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `:direct` + - `:wait` - - `class Program` + - `actions: BetaComputerActionList` - - `caller_id: String` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The call ID of the program item that produced this tool call. + - `class Click` - - `type: :program` + A click action. - - `:program` + - `class DoubleClick` - - `created_by: String` + A double click action. - The ID of the entity that created this tool call. + - `class Drag` - - `class BetaResponseApplyPatchToolCallOutput` + A drag action. - The output emitted by an apply patch tool call. + - `class Keypress` - - `id: String` + A collection of keypresses the model would like to perform. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `class Move` - - `call_id: String` + A mouse move action. - The unique ID of the apply patch tool call generated by the model. + - `class Screenshot` - - `status: :completed | :failed` + A screenshot action. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `class Scroll` - - `:completed` + A scroll action. - - `:failed` + - `class Type` - - `type: :apply_patch_call_output` + An action to type in text. - The type of the item. Always `apply_patch_call_output`. + - `class Wait` - - `:apply_patch_call_output` + A wait action. - `agent: Agent{ agent_name}` @@ -63997,59 +74385,58 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class ComputerCallOutput` - The execution context that produced this tool call. + The output of a computer tool call. - - `class Direct` + - `call_id: String` - - `type: :direct` + The ID of the computer tool call that produced the output. - - `:direct` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `class Program` + A computer screenshot image used with the computer use tool. - - `caller_id: String` + - `type: :computer_screenshot` - The call ID of the program item that produced this tool call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: :program` + - `:computer_screenshot` - - `:program` + - `file_id: String` - - `created_by: String` + The identifier of an uploaded file that contains the screenshot. - The ID of the entity that created this tool call output. + - `image_url: String` - - `output: String` + The URL of the screenshot image. - Optional textual output returned by the apply patch tool. + - `type: :computer_call_output` - - `class McpCall` + The type of the computer tool call output. Always `computer_call_output`. - An invocation of a tool on an MCP server. + - `:computer_call_output` - `id: String` - The unique ID of the tool call. - - - `arguments: String` + The ID of the computer tool call output. - A JSON string of the arguments passed to the tool. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `name: String` + The safety checks reported by the API that have been acknowledged by the developer. - 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: String` - - `type: :mcp_call` + The type of the pending safety check. - The type of the item. Always `mcp_call`. + - `message: String` - - `:mcp_call` + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -64059,22 +74446,9 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `approval_request_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. - - - `error: String` - - The error from the tool call, if any. - - - `output: String` - - The output from the tool call. - - - `status: :in_progress | :completed | :incomplete | 2 more` + - `status: :in_progress | :completed | :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` @@ -64082,115 +74456,101 @@ puts(beta_compacted_response) - `:incomplete` - - `:calling` - - - `:failed` - - - `class McpListTools` + - `class BetaResponseFunctionWebSearch` - A list of tools available on an MCP server. + 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 list. - - - `server_label: String` - - The label of the MCP server. - - - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - The tools available on the server. - - - `input_schema: untyped` - - The JSON schema describing the tool's input. + The unique ID of the web search tool call. - - `name: String` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - The name of the tool. + 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). - - `annotations: untyped` + - `class Search` - Additional annotations about the tool. + Action type "search" - Performs a web search query. - - `description: String` + - `type: :search` - The description of the tool. + The action type. - - `type: :mcp_list_tools` + - `:search` - The type of the item. Always `mcp_list_tools`. + - `queries: Array[String]` - - `:mcp_list_tools` + The search queries. - - `agent: Agent{ agent_name}` + - `query: String` - The agent that produced this item. + The search query. - - `agent_name: String` + - `sources: Array[Source{ type, url}]` - The canonical name of the agent that produced this item. + The sources used in the search. - - `error: String` + - `type: :url` - Error message if the server could not list tools. + The type of source. Always `url`. - - `class McpApprovalRequest` + - `:url` - A request for human approval of a tool invocation. + - `url: String` - - `id: String` + The URL of the source. - The unique ID of the approval request. + - `class OpenPage` - - `arguments: String` + Action type "open_page" - Opens a specific URL from search results. - A JSON string of arguments for the tool. + - `type: :open_page` - - `name: String` + The action type. - The name of the tool to run. + - `:open_page` - - `server_label: String` + - `url: String` - The label of the MCP server making the request. + The URL opened by the model. - - `type: :mcp_approval_request` + - `class FindInPage` - The type of the item. Always `mcp_approval_request`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `:mcp_approval_request` + - `pattern: String` - - `agent: Agent{ 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` - - `class McpApprovalResponse` + - `url: String` - A response to an MCP approval request. + The URL of the page searched for the pattern. - - `id: String` + - `status: :in_progress | :searching | :completed | :failed` - The unique ID of the approval response + The status of the web search tool call. - - `approval_request_id: String` + - `:in_progress` - The ID of the approval request being answered. + - `:searching` - - `approve: bool` + - `:completed` - Whether the request was approved. + - `:failed` - - `type: :mcp_approval_response` + - `type: :web_search_call` - The type of the item. Always `mcp_approval_response`. + The type of the web search tool call. Always `web_search_call`. - - `:mcp_approval_response` + - `:web_search_call` - `agent: Agent{ agent_name}` @@ -64200,2215 +74560,2157 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `reason: String` - - Optional reason for the decision. - - - `class BetaResponseCustomToolCall` - - A call to a custom tool created by the model. - - - `class BetaResponseCustomToolCallOutputItem` - - The output of a custom tool call from your code, being sent back to the model. - - - `id: String` - - The unique ID of the custom tool call output item. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` + - `class BetaResponseFunctionToolCall` - - `:incomplete` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `created_by: String` + - `arguments: String` - The identifier of the actor that created the item. + A JSON string of the arguments to pass to the function. - - `parallel_tool_calls: bool` + - `call_id: String` - Whether to allow the model to run tool calls in parallel. + The unique ID of the function tool call generated by the model. - - `temperature: Float` + - `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 name of the function to run. - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `type: :function_call` - 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 function tool call. Always `function_call`. - - `BetaToolChoiceOptions = :none | :auto | :required` + - `:function_call` - Controls which (if any) tool is called by the model. + - `id: String` - `none` means the model will not call any tool and instead generates a message. + The unique ID of the function tool call. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `agent: Agent{ agent_name}` - `required` means the model must call one or more tools. + The agent that produced this item. - - `:none` + - `agent_name: String` - - `:auto` + The canonical name of the agent that produced this item. - - `:required` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class BetaToolChoiceAllowed` + The execution context that produced this tool call. - Constrains the tools available to the model to a pre-defined set. + - `class Direct` - - `mode: :auto | :required` + - `type: :direct` - Constrains the tools available to the model to a pre-defined set. + - `:direct` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `class Program` - `required` requires the model to call one or more of the allowed tools. + - `caller_id: String` - - `:auto` + The call ID of the program item that produced this tool call. - - `:required` + - `type: :program` - - `tools: Array[Hash[Symbol, untyped]]` + - `:program` - A list of tool definitions that the model should be allowed to call. + - `namespace: String` - For the Responses API, the list of tool definitions might look like: + The namespace of the function to run. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `status: :in_progress | :completed | :incomplete` - - `type: :allowed_tools` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Allowed tool configuration type. Always `allowed_tools`. + - `:in_progress` - - `:allowed_tools` + - `:completed` - - `class BetaToolChoiceTypes` + - `:incomplete` - 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). + - `class FunctionCallOutput` - - `type: :file_search | :web_search_preview | :computer | 5 more` + The output of a function tool call. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `call_id: String` - Allowed values are: + The unique ID of the function tool call generated by the model. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `output: String | BetaResponseFunctionCallOutputItemList` - - `:file_search` + Text, image, or file output of the function tool call. - - `:web_search_preview` + - `String = String` - - `:computer` + A JSON string of the output of the function tool call. - - `:computer_use_preview` + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `:computer_use` + An array of content outputs (text, image, file) for the function tool call. - - `:web_search_preview_2025_03_11` + - `class BetaResponseInputTextContent` - - `:image_generation` + A text input to the model. - - `:code_interpreter` + - `text: String` - - `class BetaToolChoiceFunction` + The text input to the model. - Use this option to force the model to call a specific function. + - `type: :input_text` - - `name: String` + The type of the input item. Always `input_text`. - The name of the function to call. + - `:input_text` - - `type: :function` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - For function calling, the type is 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` - - `class BetaToolChoiceMcp` + The breakpoint mode. Always `explicit`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `:explicit` - - `server_label: String` + - `class BetaResponseInputImageContent` - The label of the MCP server to use. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `type: :mcp` + - `type: :input_image` - For MCP tools, the type is always `mcp`. + The type of the input item. Always `input_image`. - - `:mcp` + - `:input_image` - - `name: String` + - `detail: :low | :high | :auto | :original` - The name of the tool to call on the server. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class BetaToolChoiceCustom` + - `:low` - Use this option to force the model to call a specific custom tool. + - `:high` - - `name: String` + - `:auto` - The name of the custom tool to call. + - `:original` - - `type: :custom` + - `file_id: String` - For custom tool calling, the type is always `custom`. + The ID of the file to be sent to the model. - - `:custom` + - `image_url: String` - - `class BetaSpecificProgrammaticToolCallingParam` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: :programmatic_tool_calling` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The tool to call. Always `programmatic_tool_calling`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:programmatic_tool_calling` + - `mode: :explicit` - - `class BetaToolChoiceApplyPatch` + The breakpoint mode. Always `explicit`. - Forces the model to call the apply_patch tool when executing a tool call. + - `:explicit` - - `type: :apply_patch` + - `class BetaResponseInputFileContent` - The tool to call. Always `apply_patch`. + A file input to the model. - - `:apply_patch` + - `type: :input_file` - - `class BetaToolChoiceShell` + The type of the input item. Always `input_file`. - Forces the model to call the shell tool when a tool call is required. + - `:input_file` - - `type: :shell` + - `detail: :auto | :low | :high` - The tool to call. Always `shell`. + 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`. - - `:shell` + - `:auto` - - `tools: Array[BetaTool]` + - `:low` - 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. + - `:high` - We support the following categories of tools: + - `file_data: 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 base64-encoded data of the file to be sent to the model. - - `class BetaFunctionTool` + - `file_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 file to be sent to the model. - - `class BetaFileSearchTool` + - `file_url: 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 URL of the file to be sent to the model. - - `class BetaComputerTool` + - `filename: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The name of the file to be sent to the model. - - `class BetaComputerUsePreviewTool` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `class BetaWebSearchTool` + - `mode: :explicit` - 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 breakpoint mode. Always `explicit`. - - `class Mcp` + - `: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). + - `type: :function_call_output` - - `class CodeInterpreter` + The type of the function tool call output. Always `function_call_output`. - A tool that runs Python code to help generate a response to a prompt. + - `:function_call_output` - - `class ProgrammaticToolCalling` + - `id: String` - - `class ImageGeneration` + The unique ID of the function tool call output. Populated when this item is returned via API. - A tool that generates images using the GPT image models. + - `agent: Agent{ agent_name}` - - `class LocalShell` + The agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `agent_name: String` - - `class BetaFunctionShellTool` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class BetaCustomTool` + The execution context that produced this tool 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) + - `class Direct` - - `class BetaNamespaceTool` + - `type: :direct` - Groups function/custom tools under a shared namespace. + The caller type. Always `direct`. - - `class BetaToolSearchTool` + - `:direct` - Hosted or BYOT tool search configuration for deferred tools. + - `class Program` - - `class BetaWebSearchPreviewTool` + - `caller_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 that produced this tool call. - - `class BetaApplyPatchTool` + - `type: :program` - Allows the assistant to create, delete, or update files using unified diffs. + The caller type. Always `program`. - - `top_p: Float` + - `: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. + - `status: :in_progress | :completed | :incomplete` - We generally recommend altering this or `temperature` but not both. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `background: bool` + - `:in_progress` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `:completed` - - `completed_at: Float` + - `:incomplete` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `class AgentMessage` - - `conversation: Conversation{ id}` + A message routed between agents. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `author: String` - - `id: String` + The sending agent identity. - The unique ID of the conversation that this response was associated with. + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `max_output_tokens: Integer` + Plaintext, image, or encrypted content sent between agents. - 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). + - `class BetaResponseInputTextContent` - - `max_tool_calls: Integer` + A text input to the model. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `class BetaResponseInputImageContent` - - `moderation: Moderation{ input, output}` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Moderation results for the response input and output, if moderated completions were requested. + - `class EncryptedContent` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - Moderation for the response input. + - `encrypted_content: String` - - `class ModerationResult` + Opaque encrypted content. - A moderation result produced for the response input or output. + - `type: :encrypted_content` - - `categories: Hash[Symbol, bool]` + The type of the input item. Always `encrypted_content`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `:encrypted_content` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `recipient: String` - Which modalities of input are reflected by the score for each category. + The destination agent identity. - - `:text` + - `type: :agent_message` - - `:image` + The item type. Always `agent_message`. - - `category_scores: Hash[Symbol, Float]` + - `:agent_message` - A dictionary of moderation categories to scores. + - `id: String` - - `flagged: bool` + The unique ID of this agent message item. - A boolean indicating whether the content was flagged by any category. + - `agent: Agent{ 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. + - `class MultiAgentCall` - - `:moderation_result` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `class Error` + The multi-agent action that was executed. - An error produced while attempting moderation for the response input or output. + - `:spawn_agent` - - `code: String` + - `:interrupt_agent` - The error code. + - `:list_agents` - - `message: String` + - `:send_message` - The error message. + - `:followup_task` - - `type: :error` + - `:wait_agent` - The object type, which was always `error` for moderation failures. + - `arguments: String` - - `:error` + The action arguments as a JSON string. - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `call_id: String` - Moderation for the response output. + The unique ID linking this call to its output. - - `class ModerationResult` + - `type: :multi_agent_call` - A moderation result produced for the response input or output. + The item type. Always `multi_agent_call`. - - `categories: Hash[Symbol, bool]` + - `:multi_agent_call` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `id: String` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The unique ID of this multi-agent call. - Which modalities of input are reflected by the score for each category. + - `agent: Agent{ agent_name}` - - `:text` + The agent that produced this item. - - `:image` + - `agent_name: String` - - `category_scores: Hash[Symbol, Float]` + The canonical name of the agent that produced this item. - A dictionary of moderation categories to scores. + - `class MultiAgentCallOutput` - - `flagged: bool` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - A boolean indicating whether the content was flagged by any category. + The multi-agent action that produced this result. - - `model: String` + - `:spawn_agent` - The moderation model that produced this result. + - `:interrupt_agent` - - `type: :moderation_result` + - `:list_agents` - The object type, which was always `moderation_result` for successful moderation results. + - `:send_message` - - `:moderation_result` + - `:followup_task` - - `class Error` + - `:wait_agent` - An error produced while attempting moderation for the response input or output. + - `call_id: String` - - `code: String` + The unique ID of the multi-agent call. - The error code. + - `output: Array[Output{ text, type, annotations}]` - - `message: String` + Text output returned by the multi-agent action. - The error message. + - `text: String` - - `type: :error` + The text content. - The object type, which was always `error` for moderation failures. + - `type: :output_text` - - `:error` + The content type. Always `output_text`. - - `previous_response_id: String` + - `:output_text` - 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`. + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `prompt: BetaResponsePrompt` + Citations associated with the text content. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `id: String` + - `file_id: String` - The unique identifier of the prompt template to use. + The ID of the file. - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `filename: 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 filename of the file cited. - - `String = String` + - `index: Integer` - - `class BetaResponseInputText` + The index of the file in the list of files. - A text input to the model. + - `type: :file_citation` - - `class BetaResponseInputImage` + The citation type. Always `file_citation`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:file_citation` - - `class BetaResponseInputFile` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - A file input to the model. + - `end_index: Integer` - - `version: String` + The index of the last character of the citation in the message. - Optional version of the prompt template. + - `start_index: Integer` - - `prompt_cache_key: String` + The index of the first character of the citation in the message. - 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). + - `title: String` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + The title of the cited resource. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `type: :url_citation` - - `mode: :implicit | :explicit` + The citation type. Always `url_citation`. - Whether implicit prompt-cache breakpoints were enabled. + - `:url_citation` - - `:implicit` + - `url: String` - - `:explicit` + The URL of the cited resource. - - `ttl: :"30m"` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - The minimum lifetime applied to each cache breakpoint. + - `container_id: String` - - `:"30m"` + The ID of the container. - - `prompt_cache_retention: :in_memory | :"24h"` + - `end_index: Integer` - Deprecated. Use `prompt_cache_options.ttl` instead. + The index of the last character of the citation in the message. - 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. + - `file_id: String` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The ID of the container file. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `filename: String` - - `:in_memory` + The filename of the container file cited. - - `:"24h"` + - `start_index: Integer` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + The index of the first character of the citation in the message. - **gpt-5 and o-series models only** + - `type: :container_file_citation` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The citation type. Always `container_file_citation`. - - `context: :auto | :current_turn | :all_turns` + - `:container_file_citation` - 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: :multi_agent_call_output` - - `:auto` + The item type. Always `multi_agent_call_output`. - - `:current_turn` + - `:multi_agent_call_output` - - `:all_turns` + - `id: String` - - `effort: :none | :minimal | :low | 4 more` + The unique ID of this multi-agent 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. + - `agent: Agent{ 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` + - `class ToolSearchCall` - - `:high` + - `arguments: untyped` - - `:xhigh` + The arguments supplied to the tool search call. - - `:max` + - `type: :tool_search_call` - - `generate_summary: :auto | :concise | :detailed` + The item type. Always `tool_search_call`. - **Deprecated:** use `summary` instead. + - `: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`. + - `id: String` - - `:auto` + The unique ID of this tool search call. - - `:concise` + - `agent: Agent{ agent_name}` - - `:detailed` + The agent that produced this item. - - `mode: String | :standard | :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. + - `call_id: String` - - `String = String` + The unique ID of the tool search call generated by the model. - - `Mode = :standard | :pro` + - `execution: :server | :client` - Controls the reasoning execution mode for the request. + Whether tool search was executed by the server or by the client. - When returned on a response, this is the effective execution mode. + - `:server` - - `:standard` + - `:client` - - `:pro` + - `status: :in_progress | :completed | :incomplete` - - `summary: :auto | :concise | :detailed` + The status of the 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`. + - `:in_progress` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `:completed` - - `:auto` + - `:incomplete` - - `:concise` + - `class BetaResponseToolSearchOutputItemParam` - - `:detailed` + - `tools: Array[BetaTool]` - - `safety_identifier: String` + The loaded tool definitions returned by the 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). + - `class BetaFunctionTool` - - `service_tier: :auto | :default | :flex | 2 more` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Specifies the processing type used for serving the request. + - `name: 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'. + The name of the function to 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. + - `parameters: Hash[Symbol, untyped]` - - `:auto` + A JSON schema object describing the parameters of the function. - - `:default` + - `strict: bool` - - `:flex` + Whether strict parameter validation is enforced for this function tool. - - `:scale` + - `type: :function` - - `:priority` + The type of the function tool. Always `function`. - - `status: BetaResponseStatus` + - `:function` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:completed` + The tool invocation context(s). - - `:failed` + - `:direct` - - `:in_progress` + - `:programmatic` - - `:cancelled` + - `defer_loading: bool` - - `:queued` + Whether this function is deferred and loaded via tool search. - - `:incomplete` + - `description: String` - - `text: BetaResponseTextConfig` + A description of the function. Used by the model to determine whether or not to call the function. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `output_schema: Hash[Symbol, untyped]` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `format_: BetaResponseFormatTextConfig` + - `class BetaFileSearchTool` - An object specifying the format that the model must 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). - 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: :file_search` - The default format is `{ "type": "text" }` with no additional options. + The type of the file search tool. Always `file_search`. - **Not recommended for gpt-4o and newer models:** + - `: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. + - `vector_store_ids: Array[String]` - - `class Text` + The IDs of the vector stores to search. - Default response format. Used to generate text responses. + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `type: :text` + A filter to apply. - The type of response format being defined. Always `text`. + - `class ComparisonFilter` - - `:text` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `class BetaResponseFormatTextJSONSchemaConfig` + - `key: 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 key to compare against the value. - - `name: String` + - `type: :eq | :ne | :gt | 5 more` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `schema: Hash[Symbol, untyped]` + - `eq`: equals + - `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 schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `:eq` - - `type: :json_schema` + - `:ne` - The type of response format being defined. Always `json_schema`. + - `:gt` - - `:json_schema` + - `:gte` - - `description: String` + - `:lt` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:lte` - - `strict: bool` + - `:in` - 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). + - `:nin` - - `class JSONObject` + - `value: String | Float | bool | Array[String | Float]` - 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 value to compare against the attribute key; supports string, number, or boolean types. - - `type: :json_object` + - `String = String` - The type of response format being defined. Always `json_object`. + - `Float = Float` - - `:json_object` + - `UnionMember2 = bool` - - `verbosity: :low | :medium | :high` + - `UnionMember3 = Array[String | Float]` - 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 = String` - - `:low` + - `Float = Float` - - `:medium` + - `class CompoundFilter` - - `:high` + Combine multiple filters using `and` or `or`. - - `top_logprobs: Integer` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - 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. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `truncation: :auto | :disabled` + - `class ComparisonFilter` - The truncation strategy to use for the model response. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `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. + - `key: String` - - `:auto` + The key to compare against the value. - - `:disabled` + - `type: :eq | :ne | :gt | 5 more` - - `usage: BetaResponseUsage` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `input_tokens: Integer` + - `:eq` - The number of input tokens. + - `:ne` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `:gt` - A detailed breakdown of the input tokens. + - `:gte` - - `cache_write_tokens: Integer` + - `:lt` - The number of input tokens that were written to the cache. + - `:lte` - - `cached_tokens: Integer` + - `:in` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `:nin` - - `output_tokens: Integer` + - `value: String | Float | bool | Array[String | Float]` - The number of output tokens. + The value to compare against the attribute key; supports string, number, or boolean types. - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `String = String` - A detailed breakdown of the output tokens. + - `Float = Float` - - `reasoning_tokens: Integer` + - `UnionMember2 = bool` - The number of reasoning tokens. + - `UnionMember3 = Array[String | Float]` - - `total_tokens: Integer` + - `String = String` - The total number of tokens used. + - `Float = Float` - - `user: String` + - `UnionMember1 = untyped` - 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: :and | :or` - - `sequence_number: Integer` + Type of operation: `and` or `or`. - The sequence number for this event. + - `:and` - - `type: :"response.completed"` + - `:or` - The type of the event. Always `response.completed`. + - `max_num_results: Integer` - - `:"response.completed"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `agent: Agent{ agent_name}` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The agent that owns this multi-agent streaming event. + Ranking options for search. - - `agent_name: String` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - The canonical name of the agent that produced this item. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. -### Beta Response Computer Tool Call + - `embedding_weight: Float` -- `class BetaResponseComputerToolCall` + The weight of the embedding in the reciprocal ranking fusion. - 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_weight: Float` - - `id: String` + The weight of the text in the reciprocal ranking fusion. - The unique ID of the computer call. + - `ranker: :auto | :"default-2024-11-15"` - - `call_id: String` + The ranker to use for the file search. - An identifier used when responding to the tool call with output. + - `:auto` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `:"default-2024-11-15"` - The pending safety checks for the computer call. + - `score_threshold: Float` - - `id: String` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The ID of the pending safety check. + - `class BetaComputerTool` - - `code: String` + 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 pending safety check. + - `type: :computer` - - `message: String` + The type of the computer tool. Always `computer`. - Details about the pending safety check. + - `:computer` - - `status: :in_progress | :completed | :incomplete` + - `class BetaComputerUsePreviewTool` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when 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: Integer` - - `:completed` + The height of the computer display. - - `:incomplete` + - `display_width: Integer` - - `type: :computer_call` + The width of the computer display. - The type of the computer call. Always `computer_call`. + - `environment: :windows | :mac | :linux | 2 more` - - `:computer_call` + The type of computer environment to control. - - `action: BetaComputerAction` + - `:windows` - A click action. + - `:mac` - - `class Click` + - `:linux` - A click action. + - `:ubuntu` - - `button: :left | :right | :wheel | 2 more` + - `:browser` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: :computer_use_preview` - - `:left` + The type of the computer use tool. Always `computer_use_preview`. - - `:right` + - `:computer_use_preview` - - `:wheel` + - `class BetaWebSearchTool` - - `:back` + 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). - - `:forward` + - `type: :web_search | :web_search_2025_08_26` - - `type: :click` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Specifies the event type. For a click action, this property is always `click`. + - `:web_search` - - `:click` + - `:web_search_2025_08_26` - - `x: Integer` + - `filters: Filters{ allowed_domains}` - The x-coordinate where the click occurred. + Filters for the search. - - `y_: Integer` + - `allowed_domains: Array[String]` - The y-coordinate where the click occurred. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `keys: Array[String]` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The keys being held while clicking. + - `search_context_size: :low | :medium | :high` - - `class DoubleClick` + High 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 double click action. + - `:low` - - `keys: Array[String]` + - `:medium` - The keys being held while double-clicking. + - `:high` - - `type: :double_click` + - `user_location: UserLocation{ city, country, region, 2 more}` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The approximate location of the user. - - `:double_click` + - `city: String` - - `x: Integer` + Free text input for the city of the user, e.g. `San Francisco`. - The x-coordinate where the double click occurred. + - `country: String` - - `y_: Integer` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The y-coordinate where the double click occurred. + - `region: String` - - `class Drag` + Free text input for the region of the user, e.g. `California`. - A drag action. + - `timezone: String` - - `path: Array[Path{ x, y_}]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `type: :approximate` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of location approximation. Always `approximate`. - - `x: Integer` + - `:approximate` - The x-coordinate. + - `class Mcp` - - `y_: Integer` + 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 y-coordinate. + - `server_label: String` - - `type: :drag` + A label for this MCP server, used to identify it in tool calls. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: :mcp` - - `:drag` + The type of the MCP tool. Always `mcp`. - - `keys: Array[String]` + - `:mcp` - The keys being held while dragging the mouse. + - `allowed_callers: Array[:direct | :programmatic]` - - `class Keypress` + The tool invocation context(s). - A collection of keypresses the model would like to perform. + - `:direct` - - `keys: Array[String]` + - `:programmatic` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `type: :keypress` + List of allowed tool names or a filter object. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `McpAllowedTools = Array[String]` - - `:keypress` + A string array of allowed tool names - - `class Move` + - `class McpToolFilter` - A mouse move action. + A filter object to specify which tools are allowed. - - `type: :move` + - `read_only: bool` - Specifies the event type. For a move action, this property is always set to `move`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:move` + - `tool_names: Array[String]` - - `x: Integer` + List of allowed tool names. - The x-coordinate to move to. + - `authorization: String` - - `y_: Integer` + 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 y-coordinate to move to. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `keys: Array[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 keys being held while moving the mouse. + Currently supported `connector_id` values are: - - `class Screenshot` + - 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 screenshot action. + - `:connector_dropbox` - - `type: :screenshot` + - `:connector_gmail` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `:connector_googlecalendar` - - `:screenshot` + - `:connector_googledrive` - - `class Scroll` + - `:connector_microsoftteams` - A scroll action. + - `:connector_outlookcalendar` - - `scroll_x: Integer` + - `:connector_outlookemail` - The horizontal scroll distance. + - `:connector_sharepoint` - - `scroll_y: Integer` + - `defer_loading: bool` - The vertical scroll distance. + Whether this MCP tool is deferred and discovered via tool search. - - `type: :scroll` + - `headers: Hash[Symbol, String]` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `:scroll` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `x: Integer` + Specify which of the MCP server's tools require approval. - The x-coordinate where the scroll occurred. + - `class McpToolApprovalFilter` - - `y_: Integer` + 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 y-coordinate where the scroll occurred. + - `always: Always{ read_only, tool_names}` - - `keys: Array[String]` + A filter object to specify which tools are allowed. - The keys being held while scrolling. + - `read_only: bool` - - `class 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. - An action to type in text. + - `tool_names: Array[String]` - - `text: String` + List of allowed tool names. - The text to type. + - `never: Never{ 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: bool` - - `: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. - - `class Wait` + - `tool_names: Array[String]` - A wait action. + List of allowed tool names. - - `type: :wait` + - `McpToolApprovalSetting = :always | :never` - Specifies the event type. For a wait action, this property is always set to `wait`. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `:wait` + - `:always` - - `actions: BetaComputerActionList` + - `:never` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `server_description: String` - - `class Click` + Optional description of the MCP server, used to provide more context. - A click action. + - `server_url: String` - - `class DoubleClick` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A double click action. + - `tunnel_id: String` - - `class Drag` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - A drag action. + - `class CodeInterpreter` - - `class Keypress` + A tool that runs Python code to help generate a response to a prompt. - A collection of keypresses the model would like to perform. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `class Move` + 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 mouse move action. + - `String = String` - - `class Screenshot` + The container ID. - A screenshot action. + - `class CodeInterpreterToolAuto` - - `class Scroll` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A scroll action. + - `type: :auto` - - `class Type` + Always `auto`. - An action to type in text. + - `:auto` - - `class Wait` + - `file_ids: Array[String]` - A wait action. + An optional list of uploaded files to make available to your code. - - `agent: Agent{ agent_name}` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"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"` -### Beta Response Computer Tool Call Output Item + - `:"16g"` -- `class BetaResponseComputerToolCallOutputItem` + - `:"64g"` - - `id: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The unique ID of the computer call tool output. + Network access policy for the container. - - `call_id: String` + - `class BetaContainerNetworkPolicyDisabled` - The ID of the computer tool call that produced the output. + - `type: :disabled` - - `output: BetaResponseComputerToolCallOutputScreenshot` + Disable outbound network access. Always `disabled`. - A computer screenshot image used with the computer use tool. + - `:disabled` - - `type: :computer_screenshot` + - `class BetaContainerNetworkPolicyAllowlist` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `allowed_domains: Array[String]` - - `:computer_screenshot` + A list of allowed domains when type is `allowlist`. - - `file_id: String` + - `type: :allowlist` - The identifier of an uploaded file that contains the screenshot. + Allow outbound network access only to specified domains. Always `allowlist`. - - `image_url: String` + - `:allowlist` - The URL of the screenshot image. + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `status: :completed | :incomplete | :failed | :in_progress` + Optional domain-scoped secrets for allowlisted domains. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `domain: String` - - `:completed` + The domain associated with the secret. - - `:incomplete` + - `name: String` - - `:failed` + The name of the secret to inject for the domain. - - `:in_progress` + - `value: String` - - `type: :computer_call_output` + The secret value to inject for the domain. - The type of the computer tool call output. Always `computer_call_output`. + - `type: :code_interpreter` - - `:computer_call_output` + The type of the code interpreter tool. Always `code_interpreter`. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `:code_interpreter` - The safety checks reported by the API that have been acknowledged by the - developer. + - `allowed_callers: Array[:direct | :programmatic]` - - `id: String` + The tool invocation context(s). - The ID of the pending safety check. + - `:direct` - - `code: String` + - `:programmatic` - The type of the pending safety check. + - `class ProgrammaticToolCalling` - - `message: String` + - `type: :programmatic_tool_calling` - Details about the pending safety check. + The type of the tool. Always `programmatic_tool_calling`. - - `agent: Agent{ agent_name}` + - `:programmatic_tool_calling` - The agent that produced this item. + - `class ImageGeneration` - - `agent_name: String` + A tool that generates images using the GPT image models. - The canonical name of the agent that produced this item. + - `type: :image_generation` - - `created_by: String` + The type of the image generation tool. Always `image_generation`. - The identifier of the actor that created the item. + - `:image_generation` -### Beta Response Computer Tool Call Output Screenshot + - `action: :generate | :edit | :auto` -- `class BetaResponseComputerToolCallOutputScreenshot` + Whether to generate a new image or edit an existing image. Default: `auto`. - A computer screenshot image used with the computer use tool. + - `: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: :transparent | :opaque | :auto` - - `file_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 identifier of an uploaded file that contains the screenshot. + `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. - - `image_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 screenshot image. + - `:transparent` -### Beta Response Container Reference + - `:opaque` -- `class BetaResponseContainerReference` + - `:auto` - Represents a container created with /v1/containers. + - `input_fidelity: :high | :low` - - `container_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`. - - `type: :container_reference` + - `:high` - The environment type. Always `container_reference`. + - `:low` - - `:container_reference` + - `input_image_mask: InputImageMask{ file_id, image_url}` -### Beta Response Content + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). -- `BetaResponseContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile | 3 more` + - `file_id: String` - Multi-modal input and output contents. + File ID for the mask image. - - `class BetaResponseInputText` + - `image_url: String` - A text input to the model. + Base64-encoded mask image. - - `text: String` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - The text input to the model. + The image generation model to use. Default: `gpt-image-1`. - - `type: :input_text` + - `String = String` - The type of the input item. Always `input_text`. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:input_text` + The image generation model to use. Default: `gpt-image-1`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"gpt-image-1"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:"gpt-image-1-mini"` - - `mode: :explicit` + - `:"gpt-image-2"` - The breakpoint mode. Always `explicit`. + - `:"gpt-image-2-2026-04-21"` - - `:explicit` + - `:"gpt-image-1.5"` - - `class BetaResponseInputImage` + - `:"chatgpt-image-latest"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `moderation: :auto | :low` - - `detail: :low | :high | :auto | :original` + Moderation level for the generated image. Default: `auto`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:auto` - `:low` - - `:high` + - `output_compression: Integer` - - `:auto` + Compression level for the output image. Default: 100. - - `:original` + - `output_format: :png | :webp | :jpeg` - - `type: :input_image` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the input item. Always `input_image`. + - `:png` - - `:input_image` + - `:webp` - - `file_id: String` + - `:jpeg` - The ID of the file to be sent to the model. + - `partial_images: Integer` - - `image_url: String` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `quality: :low | :medium | :high | :auto` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` - - `class BetaResponseInputFile` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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`. - - `type: :input_file` + - `String = String` - The type of the input item. Always `input_file`. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `:input_file` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `detail: :auto | :low | :high` + - `:"1024x1024"` - 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`. + - `:"1024x1536"` + + - `:"1536x1024"` - `:auto` - - `:low` + - `class LocalShell` - - `:high` + A tool that allows the model to execute shell commands in a local environment. - - `file_data: String` + - `type: :local_shell` - The content of the file to be sent to the model. + The type of the local shell tool. Always `local_shell`. - - `file_id: String` + - `:local_shell` - The ID of the file to be sent to the model. + - `class BetaFunctionShellTool` - - `file_url: String` + A tool that allows the model to execute shell commands. - The URL of the file to be sent to the model. + - `type: :shell` - - `filename: String` + The type of the shell tool. Always `shell`. - The name of the file to be sent to the model. + - `:shell` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `allowed_callers: Array[:direct | :programmatic]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The tool invocation context(s). - - `mode: :explicit` + - `:direct` - The breakpoint mode. Always `explicit`. + - `:programmatic` - - `:explicit` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `class BetaResponseOutputText` + - `class BetaContainerAuto` - A text output from the model. + - `type: :container_auto` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + Automatically creates a container for this request - The annotations of the text output. + - `:container_auto` - - `class FileCitation` + - `file_ids: Array[String]` - A citation to a file. + An optional list of uploaded files to make available to your code. - - `file_id: String` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The ID of the file. + The memory limit for the container. - - `filename: String` + - `:"1g"` - The filename of the file cited. + - `:"4g"` - - `index: Integer` + - `:"16g"` - The index of the file in the list of files. + - `:"64g"` - - `type: :file_citation` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The type of the file citation. Always `file_citation`. + Network access policy for the container. - - `:file_citation` + - `class BetaContainerNetworkPolicyDisabled` - - `class URLCitation` + - `class BetaContainerNetworkPolicyAllowlist` - A citation for a web resource used to generate a model response. + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `end_index: Integer` + An optional list of skills referenced by id or inline data. - The index of the last character of the URL citation in the message. + - `class BetaSkillReference` - - `start_index: Integer` + - `skill_id: String` - The index of the first character of the URL citation in the message. + The ID of the referenced skill. - - `title: String` + - `type: :skill_reference` - The title of the web resource. + References a skill created with the /v1/skills endpoint. - - `type: :url_citation` + - `:skill_reference` - The type of the URL citation. Always `url_citation`. + - `version: String` - - `:url_citation` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `url: String` + - `class BetaInlineSkill` - The URL of the web resource. + - `description: String` - - `class ContainerFileCitation` + The description of the skill. - A citation for a container file used to generate a model response. + - `name: String` - - `container_id: String` + The name of the skill. - The ID of the container file. + - `source: BetaInlineSkillSource` - - `end_index: Integer` + Inline skill payload - The index of the last character of the container file citation in the message. + - `data: String` - - `file_id: String` + Base64-encoded skill zip bundle. - The ID of the file. + - `media_type: :"application/zip"` - - `filename: String` + The media type of the inline skill payload. Must be `application/zip`. - The filename of the container file cited. + - `:"application/zip"` - - `start_index: Integer` + - `type: :base64` - The index of the first character of the container file citation in the message. + The type of the inline skill source. Must be `base64`. - - `type: :container_file_citation` + - `:base64` - The type of the container file citation. Always `container_file_citation`. + - `type: :inline` - - `:container_file_citation` + Defines an inline skill for this request. - - `class FilePath` + - `:inline` - A path to a file. + - `class BetaLocalEnvironment` - - `file_id: String` + - `type: :local` - The ID of the file. + Use a local computer environment. - - `index: Integer` + - `:local` - The index of the file in the list of files. + - `skills: Array[BetaLocalSkill]` - - `type: :file_path` + An optional list of skills. - The type of the file path. Always `file_path`. + - `description: String` - - `:file_path` + The description of the skill. - - `text: String` + - `name: String` - The text output from the model. + The name of the skill. - - `type: :output_text` + - `path: String` - The type of the output text. Always `output_text`. + The path to the directory containing the skill. - - `:output_text` + - `class BetaContainerReference` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `container_id: String` - - `token: String` + The ID of the referenced container. - - `bytes: Array[Integer]` + - `type: :container_reference` - - `logprob: Float` + References a container created with the /v1/containers endpoint - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `:container_reference` - - `token: String` + - `class BetaCustomTool` - - `bytes: Array[Integer]` + 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) - - `logprob: Float` + - `name: String` - - `class BetaResponseOutputRefusal` + The name of the custom tool, used to identify it in tool calls. - A refusal from the model. + - `type: :custom` - - `refusal: String` + The type of the custom tool. Always `custom`. - The refusal explanation from the model. + - `:custom` - - `type: :refusal` + - `allowed_callers: Array[:direct | :programmatic]` - The type of the refusal. Always `refusal`. + The tool invocation context(s). - - `:refusal` + - `:direct` - - `class ReasoningText` + - `:programmatic` - Reasoning text from the model. + - `defer_loading: bool` - - `text: String` + Whether this tool should be deferred and discovered via tool search. - The reasoning text from the model. + - `description: String` - - `type: :reasoning_text` + Optional description of the custom tool, used to provide more context. - The type of the reasoning text. Always `reasoning_text`. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `:reasoning_text` + The input format for the custom tool. Default is unconstrained text. -### Beta Response Content Part Added Event + - `class Text` -- `class BetaResponseContentPartAddedEvent` + Unconstrained free-form text. - Emitted when a new content part is added. + - `type: :text` - - `content_index: Integer` + Unconstrained text format. Always `text`. - The index of the content part that was added. + - `:text` - - `item_id: String` + - `class Grammar` - The ID of the output item that the content part was added to. + A grammar defined by the user. - - `output_index: Integer` + - `definition: String` - The index of the output item that the content part was added to. + The grammar definition. - - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` + - `syntax: :lark | :regex` - The content part that was added. + The syntax of the grammar definition. One of `lark` or `regex`. - - `class BetaResponseOutputText` + - `:lark` - A text output from the model. + - `:regex` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `type: :grammar` - The annotations of the text output. + Grammar format. Always `grammar`. - - `class FileCitation` + - `:grammar` - A citation to a file. + - `class BetaNamespaceTool` - - `file_id: String` + Groups function/custom tools under a shared namespace. - The ID of the file. + - `description: String` - - `filename: String` + A description of the namespace shown to the model. - The filename of the file cited. + - `name: String` - - `index: Integer` + The namespace name used in tool calls (for example, `crm`). - The index of the file in the list of files. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `type: :file_citation` + The function/custom tools available inside this namespace. - The type of the file citation. Always `file_citation`. + - `class Function` - - `:file_citation` + - `name: String` - - `class URLCitation` + - `type: :function` - A citation for a web resource used to generate a model response. + - `:function` - - `end_index: Integer` + - `allowed_callers: Array[:direct | :programmatic]` - The index of the last character of the URL citation in the message. + The tool invocation context(s). - - `start_index: Integer` + - `:direct` - The index of the first character of the URL citation in the message. + - `:programmatic` - - `title: String` + - `defer_loading: bool` - The title of the web resource. + Whether this function should be deferred and discovered via tool search. - - `type: :url_citation` + - `description: String` - The type of the URL citation. Always `url_citation`. + - `output_schema: Hash[Symbol, untyped]` - - `:url_citation` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `url: String` + - `parameters: untyped` - The URL of the web resource. + - `strict: bool` - - `class ContainerFileCitation` + 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 citation for a container file used to generate a model response. + - `class BetaCustomTool` - - `container_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 container file. + - `type: :namespace` - - `end_index: Integer` + The type of the tool. Always `namespace`. - The index of the last character of the container file citation in the message. + - `:namespace` - - `file_id: String` + - `class BetaToolSearchTool` - The ID of the file. + Hosted or BYOT tool search configuration for deferred tools. - - `filename: String` + - `type: :tool_search` - The filename of the container file cited. + The type of the tool. Always `tool_search`. - - `start_index: Integer` + - `:tool_search` - The index of the first character of the container file citation in the message. + - `description: String` - - `type: :container_file_citation` + Description shown to the model for a client-executed tool search tool. - The type of the container file citation. Always `container_file_citation`. + - `execution: :server | :client` - - `:container_file_citation` + Whether tool search is executed by the server or by the client. - - `class FilePath` + - `:server` - A path to a file. + - `:client` - - `file_id: String` + - `parameters: untyped` - The ID of the file. + Parameter schema for a client-executed tool search tool. - - `index: Integer` + - `class BetaWebSearchPreviewTool` - The index of the file in the list of files. + 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: :file_path` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - The type of the file path. Always `file_path`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `:file_path` + - `:web_search_preview` - - `text: String` + - `:web_search_preview_2025_03_11` - The text output from the model. + - `search_content_types: Array[:text | :image]` - - `type: :output_text` + - `:text` - The type of the output text. Always `output_text`. + - `:image` - - `:output_text` + - `search_context_size: :low | :medium | :high` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `token: String` + - `:low` + + - `:medium` + + - `:high` + + - `user_location: UserLocation{ type, city, country, 2 more}` + + The user's location. - - `bytes: Array[Integer]` + - `type: :approximate` - - `logprob: Float` + The type of location approximation. Always `approximate`. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `:approximate` - - `token: String` + - `city: String` - - `bytes: Array[Integer]` + Free text input for the city of the user, e.g. `San Francisco`. - - `logprob: Float` + - `country: String` - - `class BetaResponseOutputRefusal` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A refusal from the model. + - `region: String` - - `refusal: String` + Free text input for the region of the user, e.g. `California`. - The refusal explanation from the model. + - `timezone: String` - - `type: :refusal` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the refusal. Always `refusal`. + - `class BetaApplyPatchTool` - - `:refusal` + Allows the assistant to create, delete, or update files using unified diffs. - - `class ReasoningText` + - `type: :apply_patch` - Reasoning text from the model. + The type of the tool. Always `apply_patch`. - - `text: String` + - `:apply_patch` - The reasoning text from the model. + - `allowed_callers: Array[:direct | :programmatic]` - - `type: :reasoning_text` + The tool invocation context(s). - The type of the reasoning text. Always `reasoning_text`. + - `:direct` - - `:reasoning_text` + - `:programmatic` - - `sequence_number: Integer` + - `type: :tool_search_output` - The sequence number of this event. + The item type. Always `tool_search_output`. - - `type: :"response.content_part.added"` + - `:tool_search_output` - The type of the event. Always `response.content_part.added`. + - `id: String` - - `:"response.content_part.added"` + The unique ID of this tool search output. - `agent: Agent{ 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 Content Part Done Event + - `call_id: String` -- `class BetaResponseContentPartDoneEvent` + The unique ID of the tool search call generated by the model. - Emitted when a content part is done. + - `execution: :server | :client` - - `content_index: Integer` + Whether tool search was executed by the server or by the client. - The index of the content part that is done. + - `:server` - - `item_id: String` + - `:client` - The ID of the output item that the content part was added to. + - `status: :in_progress | :completed | :incomplete` - - `output_index: Integer` + The status of the tool search output. - The index of the output item that the content part was added to. + - `:in_progress` - - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` + - `:completed` - The content part that is done. + - `:incomplete` - - `class BetaResponseOutputText` + - `class AdditionalTools` - A text output from the model. + - `role: :developer` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The role that provided the additional tools. Only `developer` is supported. - The annotations of the text output. + - `:developer` - - `class FileCitation` + - `tools: Array[BetaTool]` - A citation to a file. + A list of additional tools made available at this item. - - `file_id: String` + - `class BetaFunctionTool` - The ID 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). - - `filename: String` + - `class BetaFileSearchTool` - The filename of the file cited. + 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). - - `index: Integer` + - `class BetaComputerTool` - The index of the file in the list of files. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :file_citation` + - `class BetaComputerUsePreviewTool` - The type of the file citation. Always `file_citation`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:file_citation` + - `class BetaWebSearchTool` - - `class URLCitation` + 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 citation for a web resource used to generate a model response. + - `class Mcp` - - `end_index: Integer` + 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 last character of the URL citation in the message. + - `class CodeInterpreter` - - `start_index: Integer` + A tool that runs Python code to help generate a response to a prompt. - The index of the first character of the URL citation in the message. + - `class ProgrammaticToolCalling` - - `title: String` + - `class ImageGeneration` - The title of the web resource. + A tool that generates images using the GPT image models. - - `type: :url_citation` + - `class LocalShell` - 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` + - `class BetaFunctionShellTool` - - `url: String` + A tool that allows the model to execute shell commands. - The URL of the web resource. + - `class BetaCustomTool` - - `class ContainerFileCitation` + 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 citation for a container file used to generate a model response. + - `class BetaNamespaceTool` - - `container_id: String` + Groups function/custom tools under a shared namespace. - The ID of the container file. + - `class BetaToolSearchTool` - - `end_index: Integer` + Hosted or BYOT tool search configuration for deferred tools. - The index of the last character of the container file citation in the message. + - `class BetaWebSearchPreviewTool` - - `file_id: String` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The ID of the file. + - `class BetaApplyPatchTool` - - `filename: String` + Allows the assistant to create, delete, or update files using unified diffs. - The filename of the container file cited. + - `type: :additional_tools` - - `start_index: Integer` + The item type. Always `additional_tools`. - The index of the first character of the container file citation in the message. + - `:additional_tools` - - `type: :container_file_citation` + - `id: String` - The type of the container file citation. Always `container_file_citation`. + The unique ID of this additional tools item. - - `:container_file_citation` + - `agent: Agent{ agent_name}` - - `class FilePath` + 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. + - `class BetaResponseReasoningItem` - - `index: Integer` + 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 index of the file in the list of files. + - `id: String` - - `type: :file_path` + The unique identifier of the reasoning content. - The type of the file path. Always `file_path`. + - `summary: Array[Summary{ text, type}]` - - `:file_path` + Reasoning summary content. - `text: String` - The text output from the model. + A summary of the reasoning output from the model so far. - - `type: :output_text` + - `type: :summary_text` - The type of the output text. Always `output_text`. + The type of the object. Always `summary_text`. - - `:output_text` + - `:summary_text` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `type: :reasoning` - - `token: String` + The type of the object. Always `reasoning`. - - `bytes: Array[Integer]` + - `:reasoning` - - `logprob: Float` + - `agent: Agent{ agent_name}` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + The agent that produced this item. - - `token: String` + - `agent_name: String` - - `bytes: Array[Integer]` + The canonical name of the agent that produced this item. - - `logprob: Float` + - `content: Array[Content{ text, type}]` - - `class BetaResponseOutputRefusal` + Reasoning text content. - A refusal from the model. + - `text: String` - - `refusal: String` + The reasoning text from the model. - The refusal explanation from the model. + - `type: :reasoning_text` - - `type: :refusal` + The type of the reasoning text. Always `reasoning_text`. - The type of the refusal. Always `refusal`. + - `:reasoning_text` - - `:refusal` + - `encrypted_content: String` - - `class ReasoningText` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - Reasoning text from the model. + - `status: :in_progress | :completed | :incomplete` - - `text: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The reasoning text from the model. + - `:in_progress` - - `type: :reasoning_text` + - `:completed` - The type of the reasoning text. Always `reasoning_text`. + - `:incomplete` - - `:reasoning_text` + - `class BetaResponseCompactionItemParam` - - `sequence_number: Integer` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The sequence number of this event. + - `encrypted_content: String` - - `type: :"response.content_part.done"` + The encrypted content of the compaction summary. - The type of the event. Always `response.content_part.done`. + - `type: :compaction` - - `:"response.content_part.done"` + The type of the item. Always `compaction`. + + - `:compaction` + + - `id: String` + + The ID of the compaction item. - `agent: Agent{ 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 Conversation Param - -- `class BetaResponseConversationParam` + - `class ImageGenerationCall` - The conversation that this response belongs to. + An image generation request made by the model. - `id: String` - The unique ID of the conversation. + The unique ID of the image generation call. -### Beta Response Created Event + - `result: String` -- `class BetaResponseCreatedEvent` + The generated image encoded in base64. - An event that is emitted when a response is created. + - `status: :in_progress | :completed | :generating | :failed` - - `response: BetaResponse` + The status of the image generation call. - The response that was created. + - `:in_progress` - - `id: String` + - `:completed` - Unique identifier for this Response. + - `:generating` - - `created_at: Float` + - `:failed` - Unix timestamp (in seconds) of when this Response was created. + - `type: :image_generation_call` - - `error: BetaResponseError` + The type of the image generation call. Always `image_generation_call`. - An error object returned when the model fails to generate a Response. + - `:image_generation_call` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `agent: Agent{ agent_name}` - The error code for the response. + The agent that produced this item. - - `:server_error` + - `agent_name: String` - - `:rate_limit_exceeded` + The canonical name of the agent that produced this item. - - `:invalid_prompt` + - `class BetaResponseCodeInterpreterToolCall` - - `:bio_policy` + A tool call to run code. - - `:vector_store_timeout` + - `id: String` - - `:invalid_image` + The unique ID of the code interpreter tool call. - - `:invalid_image_format` + - `code: String` - - `:invalid_base64_image` + The code to run, or null if not available. - - `:invalid_image_url` + - `container_id: String` - - `:image_too_large` + The ID of the container used to run the code. - - `:image_too_small` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `:image_parse_error` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `:image_content_policy_violation` + - `class Logs` - - `:invalid_image_mode` + The logs output from the code interpreter. - - `:image_file_too_large` + - `logs: String` - - `:unsupported_image_media_type` + The logs output from the code interpreter. - - `:empty_image_file` + - `type: :logs` - - `:failed_to_download_image` + The type of the output. Always `logs`. - - `:image_file_not_found` + - `:logs` - - `message: String` + - `class Image` - A human-readable description of the error. + The image output from the code interpreter. - - `incomplete_details: IncompleteDetails{ reason}` + - `type: :image` - Details about why the response is incomplete. + The type of the output. Always `image`. - - `reason: :max_output_tokens | :content_filter` + - `:image` - The reason why the response is incomplete. + - `url: String` - - `:max_output_tokens` + The URL of the image output from the code interpreter. - - `:content_filter` + - `status: :in_progress | :completed | :incomplete | 2 more` - - `instructions: String | Array[BetaResponseInputItem]` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - 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 = String` + - `:incomplete` - A text input to the model, equivalent to a text input with the - `developer` role. + - `:interpreting` - - `InputItemList = Array[BetaResponseInputItem]` + - `:failed` - A list of one or many input items to the model, containing - different content types. + - `type: :code_interpreter_call` - - `class BetaEasyInputMessage` + The type of the code interpreter tool call. Always `code_interpreter_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. + - `:code_interpreter_call` - - `content: String | BetaResponseInputMessageContentList` + - `agent: Agent{ agent_name}` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The agent that produced this item. - - `String = String` + - `agent_name: String` - A text input to the model. + The canonical name of the agent that produced this item. - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `class LocalShellCall` - A list of one or many input items to the model, containing different content - types. + A tool call to run a command on the local shell. - - `class BetaResponseInputText` + - `id: String` - A text input to the model. + The unique ID of the local shell call. - - `text: String` + - `action: Action{ command, env, type, 3 more}` - The text input to the model. + Execute a shell command on the server. - - `type: :input_text` + - `command: Array[String]` - The type of the input item. Always `input_text`. + The command to run. - - `:input_text` + - `env: Hash[Symbol, String]` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Environment variables to set for the command. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: :exec` - - `mode: :explicit` + The type of the local shell action. Always `exec`. - The breakpoint mode. Always `explicit`. + - `:exec` - - `:explicit` + - `timeout_ms: Integer` - - `class BetaResponseInputImage` + Optional timeout in milliseconds for the command. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `user: String` - - `detail: :low | :high | :auto | :original` + Optional user to run the command as. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `working_directory: String` - - `:low` + Optional working directory to run the command in. - - `:high` + - `call_id: String` - - `:auto` + The unique ID of the local shell tool call generated by the model. - - `:original` + - `status: :in_progress | :completed | :incomplete` - - `type: :input_image` + The status of the local shell call. - The type of the input item. Always `input_image`. + - `:in_progress` - - `:input_image` + - `:completed` - - `file_id: String` + - `:incomplete` - The ID of the file to be sent to the model. + - `type: :local_shell_call` - - `image_url: String` + The type of the local shell call. Always `local_shell_call`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `:local_shell_call` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `agent: Agent{ 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` + - `class LocalShellCallOutput` - - `class BetaResponseInputFile` + The output of a local shell tool call. - A file input to the model. + - `id: String` - - `type: :input_file` + The unique ID of the local shell tool call generated by the model. - The type of the input item. Always `input_file`. + - `output: String` - - `:input_file` + A JSON string of the output of the local shell tool call. - - `detail: :auto | :low | :high` + - `type: :local_shell_call_output` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:auto` + - `:local_shell_call_output` - - `:low` + - `agent: Agent{ agent_name}` - - `:high` + The agent that produced this item. - - `file_data: 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: String` + - `status: :in_progress | :completed | :incomplete` - The ID of the file to be sent to the model. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `file_url: String` + - `:in_progress` - The URL of the file to be sent to the model. + - `:completed` - - `filename: String` + - `:incomplete` - The name of the file to be sent to the model. + - `class ShellCall` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A tool representing a request to execute one or more 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. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `mode: :explicit` + The shell commands and limits that describe how to run the tool call. - The breakpoint mode. Always `explicit`. + - `commands: Array[String]` - - `:explicit` + Ordered shell commands for the execution environment to run. - - `role: :user | :assistant | :system | :developer` + - `max_output_length: Integer` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `:user` + - `timeout_ms: Integer` - - `:assistant` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `:system` + - `call_id: String` - - `:developer` + The unique ID of the shell tool call generated by the model. - - `phase: :commentary` + - `type: :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. + The type of the item. Always `shell_call`. - - `:commentary` + - `:shell_call` - - `type: :message` + - `id: String` - The type of the message input. Always `message`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `:message` + - `agent: Agent{ agent_name}` - - `class Message` + The agent that produced this item. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `agent_name: String` - - `content: BetaResponseInputMessageContentList` + The canonical name of the agent that produced this item. - A list of one or many input items to the model, containing different content - types. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `role: :user | :system | :developer` + The execution context that produced this tool call. - The role of the message input. One of `user`, `system`, or `developer`. + - `class Direct` - - `:user` + - `type: :direct` - - `:system` + The caller type. Always `direct`. - - `:developer` + - `:direct` - - `agent: Agent{ agent_name}` + - `class Program` - The agent that produced this item. + - `caller_id: String` - - `agent_name: String` + The call ID of the program item that produced this tool call. - The canonical name of the agent that produced this item. + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `environment: BetaLocalEnvironment | BetaContainerReference` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment` + + - `class BetaContainerReference` - `status: :in_progress | :completed | :incomplete` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` @@ -66416,190 +76718,189 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :message` - - The type of the message input. Always set to `message`. + - `class ShellCallOutput` - - `:message` + The streamed output items emitted by a shell tool call. - - `class BetaResponseOutputMessage` + - `call_id: String` - An output message from the model. + The unique ID of the shell tool call generated by the model. - - `id: String` + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - The unique ID of the output message. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The content of the output message. + The exit or timeout outcome associated with this shell call. - - `class BetaResponseOutputText` + - `class Timeout` - A text output from the model. + Indicates that the shell call exceeded its configured time limit. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `type: :timeout` - The annotations of the text output. + The outcome type. Always `timeout`. - - `class FileCitation` + - `:timeout` - A citation to a file. + - `class Exit` - - `file_id: String` + Indicates that the shell commands finished and returned an exit code. - The ID of the file. + - `exit_code: Integer` - - `filename: String` + The exit code returned by the shell process. - The filename of the file cited. + - `type: :exit` - - `index: Integer` + The outcome type. Always `exit`. - The index of the file in the list of files. + - `:exit` - - `type: :file_citation` + - `stderr: String` - The type of the file citation. Always `file_citation`. + Captured stderr output for the shell call. - - `:file_citation` + - `stdout: String` - - `class URLCitation` + Captured stdout output for the shell call. - A citation for a web resource used to generate a model response. + - `type: :shell_call_output` - - `end_index: Integer` + The type of the item. Always `shell_call_output`. - The index of the last character of the URL citation in the message. + - `:shell_call_output` - - `start_index: Integer` + - `id: String` - The index of the first character of the URL citation in the message. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `title: String` + - `agent: Agent{ agent_name}` - The title of the web resource. + The agent that produced this item. - - `type: :url_citation` + - `agent_name: String` - The type of the URL citation. Always `url_citation`. + The canonical name of the agent that produced this item. - - `:url_citation` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `url: String` + The execution context that produced this tool call. - The URL of the web resource. + - `class Direct` - - `class ContainerFileCitation` + - `type: :direct` - A citation for a container file used to generate a model response. + The caller type. Always `direct`. - - `container_id: String` + - `:direct` - The ID of the container file. + - `class Program` - - `end_index: Integer` + - `caller_id: String` - The index of the last character of the container file citation in the message. + 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`. - - `filename: String` + - `:program` - The filename of the container file cited. + - `max_output_length: Integer` - - `start_index: Integer` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The index of the first character of the container file citation in the message. + - `status: :in_progress | :completed | :incomplete` - - `type: :container_file_citation` + The status of the shell call output. - The type of the container file citation. Always `container_file_citation`. + - `:in_progress` - - `:container_file_citation` + - `:completed` - - `class FilePath` + - `:incomplete` - A path to a file. + - `class ApplyPatchCall` - - `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` - - `index: Integer` + The unique ID of the apply patch tool call generated by the model. - The index of the file in the list of files. + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `type: :file_path` + The specific create, delete, or update instruction for the apply_patch tool call. - The type of the file path. Always `file_path`. + - `class CreateFile` - - `:file_path` + Instruction for creating a new file via the apply_patch tool. - - `text: String` + - `diff: String` - The text output from the model. + Unified diff content to apply when creating the file. - - `type: :output_text` + - `path: String` - The type of the output text. Always `output_text`. + Path of the file to create relative to the workspace root. - - `:output_text` + - `type: :create_file` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The operation type. Always `create_file`. - - `token: String` + - `:create_file` - - `bytes: Array[Integer]` + - `class DeleteFile` - - `logprob: Float` + Instruction for deleting an existing file via the apply_patch tool. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `path: String` - - `token: String` + Path of the file to delete relative to the workspace root. - - `bytes: Array[Integer]` + - `type: :delete_file` - - `logprob: Float` + The operation type. Always `delete_file`. - - `class BetaResponseOutputRefusal` + - `:delete_file` - A refusal from the model. + - `class UpdateFile` - - `refusal: String` + Instruction for updating an existing file via the apply_patch tool. - The refusal explanation from the model. + - `diff: String` - - `type: :refusal` + Unified diff content to apply to the existing file. - The type of the refusal. Always `refusal`. + - `path: String` - - `:refusal` + Path of the file to update relative to the workspace root. - - `role: :assistant` + - `type: :update_file` - The role of the output message. Always `assistant`. + The operation type. Always `update_file`. - - `:assistant` + - `:update_file` - - `status: :in_progress | :completed | :incomplete` + - `status: :in_progress | :completed` - 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 apply patch tool call. One of `in_progress` or `completed`. - `:in_progress` - `:completed` - - `:incomplete` + - `type: :apply_patch_call` - - `type: :message` + The type of the item. Always `apply_patch_call`. - The type of the output message. Always `message`. + - `:apply_patch_call` - - `:message` + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -66609,47 +76910,55 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `caller_: Direct{ type} | Program{ 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` + - `class Direct` - - `class BetaResponseFileSearchToolCall` + - `type: :direct` - 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 caller type. Always `direct`. - - `id: String` + - `:direct` - The unique ID of the file search tool call. + - `class Program` - - `queries: Array[String]` + - `caller_id: String` - The queries used to search for files. + The call ID of the program item that produced this tool call. - - `status: :in_progress | :searching | :completed | 2 more` + - `type: :program` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The caller type. Always `program`. - - `:in_progress` + - `:program` - - `:searching` + - `class ApplyPatchCallOutput` - - `:completed` + The streamed output emitted by an apply patch tool call. - - `:incomplete` + - `call_id: String` + + The unique ID of the apply patch tool call generated by the model. + + - `status: :completed | :failed` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `:completed` - `:failed` - - `type: :file_search_call` + - `type: :apply_patch_call_output` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `apply_patch_call_output`. - - `:file_search_call` + - `:apply_patch_call_output` + + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -66659,321 +76968,355 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - The results of the file search tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `attributes: Hash[Symbol, String | Float | bool]` + The execution context that produced this tool call. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `class Direct` - - `String = String` + - `type: :direct` - - `Float = Float` + The caller type. Always `direct`. - - `UnionMember2 = bool` + - `:direct` - - `file_id: String` + - `class Program` - The unique ID of the file. + - `caller_id: String` - - `filename: String` + The call ID of the program item that produced this tool call. - The name of the file. + - `type: :program` - - `score: Float` + The caller type. Always `program`. - The relevance score of the file - a value between 0 and 1. + - `:program` - - `text: String` + - `output: String` - The text that was retrieved from the file. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `class BetaResponseComputerToolCall` + - `class McpListTools` - 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 list of tools available on an MCP server. - `id: String` - The unique ID of the computer call. + The unique ID of the list. - - `call_id: String` + - `server_label: String` - An identifier used when responding to the tool call with output. + The label of the MCP server. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - The pending safety checks for the computer call. + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + A request for human approval of a tool invocation. - `id: String` - The ID of the pending safety check. + The unique ID of the approval request. - - `code: String` + - `arguments: String` - The type of the pending safety check. + A JSON string of arguments for the tool. - - `message: String` + - `name: String` - Details about the pending safety check. + The name of the tool to run. - - `status: :in_progress | :completed | :incomplete` + - `server_label: String` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The label of the MCP server making the request. - - `:in_progress` + - `type: :mcp_approval_request` - - `:completed` + The type of the item. Always `mcp_approval_request`. - - `:incomplete` + - `:mcp_approval_request` - - `type: :computer_call` + - `agent: Agent{ agent_name}` - The type of the computer call. Always `computer_call`. + The agent that produced this item. - - `:computer_call` + - `agent_name: String` - - `action: BetaComputerAction` + The canonical name of the agent that produced this item. - A click action. + - `class McpApprovalResponse` - - `class Click` + A response to an MCP approval request. - A click action. + - `approval_request_id: String` - - `button: :left | :right | :wheel | 2 more` + The ID of the approval request being answered. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `approve: bool` - - `:left` + Whether the request was approved. - - `:right` + - `type: :mcp_approval_response` - - `:wheel` + The type of the item. Always `mcp_approval_response`. - - `:back` + - `:mcp_approval_response` - - `:forward` + - `id: String` - - `type: :click` + The unique ID of the approval response - Specifies the event type. For a click action, this property is always `click`. + - `agent: Agent{ agent_name}` - - `:click` + The agent that produced this item. - - `x: Integer` + - `agent_name: String` - The x-coordinate where the click occurred. + The canonical name of the agent that produced this item. - - `y_: Integer` + - `reason: String` - The y-coordinate where the click occurred. + Optional reason for the decision. - - `keys: Array[String]` + - `class McpCall` - The keys being held while clicking. + An invocation of a tool on an MCP server. - - `class DoubleClick` + - `id: String` - A double click action. + The unique ID of the tool call. - - `keys: Array[String]` + - `arguments: String` - The keys being held while double-clicking. + A JSON string of the arguments passed to the tool. - - `type: :double_click` + - `name: String` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The name of the tool that was run. - - `:double_click` + - `server_label: String` - - `x: Integer` + The label of the MCP server running the tool. - The x-coordinate where the double click occurred. + - `type: :mcp_call` - - `y_: Integer` + The type of the item. Always `mcp_call`. - The y-coordinate where the double click occurred. + - `:mcp_call` - - `class Drag` + - `agent: Agent{ agent_name}` - A drag action. + The agent that produced this item. - - `path: Array[Path{ x, y_}]` + - `agent_name: String` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The canonical name of the agent that produced this item. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `approval_request_id: String` - - `x: Integer` + 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 x-coordinate. + - `error: String` - - `y_: Integer` + The error from the tool call, if any. - The y-coordinate. + - `output: String` - - `type: :drag` + The output from the tool call. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `:drag` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `keys: Array[String]` + - `:in_progress` - The keys being held while dragging the mouse. + - `:completed` - - `class Keypress` + - `:incomplete` - A collection of keypresses the model would like to perform. + - `:calling` - - `keys: Array[String]` + - `:failed` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `class BetaResponseCustomToolCallOutput` + + 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `type: :keypress` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `String = String` - - `:keypress` + A string of the output of the custom tool call. - - `class Move` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - A mouse move action. + Text, image, or file output of the custom tool call. - - `type: :move` + - `class BetaResponseInputText` - Specifies the event type. For a move action, this property is always set to `move`. + A text input to the model. - - `:move` + - `class BetaResponseInputImage` - - `x: Integer` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The x-coordinate to move to. + - `class BetaResponseInputFile` - - `y_: Integer` + A file input to the model. - The y-coordinate to move to. + - `type: :custom_tool_call_output` - - `keys: Array[String]` + The type of the custom tool call output. Always `custom_tool_call_output`. - The keys being held while moving the mouse. + - `:custom_tool_call_output` - - `class Screenshot` + - `id: String` - A screenshot action. + The unique ID of the custom tool call output in the OpenAI platform. - - `type: :screenshot` + - `agent: Agent{ agent_name}` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The agent that produced this item. - - `:screenshot` + - `agent_name: String` - - `class Scroll` + The canonical name of the agent that produced this item. - A scroll action. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `scroll_x: Integer` + The execution context that produced this tool call. - The horizontal scroll distance. + - `class Direct` - - `scroll_y: Integer` + - `type: :direct` - The vertical scroll distance. + The caller type. Always `direct`. - - `type: :scroll` + - `:direct` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `class Program` - - `:scroll` + - `caller_id: String` - - `x: Integer` + The call ID of the program item that produced this tool call. - The x-coordinate where the scroll occurred. + - `type: :program` - - `y_: Integer` + The caller type. Always `program`. - The y-coordinate where the scroll occurred. + - `:program` - - `keys: Array[String]` + - `class BetaResponseCustomToolCall` - The keys being held while scrolling. + A call to a custom tool created by the model. - - `class Type` + - `call_id: String` - An action to type in text. + An identifier used to map this custom tool call to a tool call output. - - `text: String` + - `input: String` - The text to type. + The input for the custom tool call generated by the model. - - `type: :type` + - `name: String` - Specifies the event type. For a type action, this property is always set to `type`. + The name of the custom tool being called. - - `:type` + - `type: :custom_tool_call` - - `class Wait` + The type of the custom tool call. Always `custom_tool_call`. - A wait action. + - `:custom_tool_call` - - `type: :wait` + - `id: String` - Specifies the event type. For a wait action, this property is always set to `wait`. + The unique ID of the custom tool call in the OpenAI platform. - - `:wait` + - `agent: Agent{ agent_name}` - - `actions: BetaComputerActionList` + The agent that produced this item. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `agent_name: String` - - `class Click` + The canonical name of the agent that produced this item. - A click action. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class DoubleClick` + The execution context that produced this tool call. - A double click action. + - `class Direct` - - `class Drag` + - `type: :direct` - A drag action. + - `:direct` - - `class Keypress` + - `class Program` - A collection of keypresses the model would like to perform. + - `caller_id: String` - - `class Move` + The call ID of the program item that produced this tool call. - A mouse move action. + - `type: :program` - - `class Screenshot` + - `:program` - A screenshot action. + - `namespace: String` - - `class Scroll` + The namespace of the custom tool being called. - A scroll action. + - `class CompactionTrigger` - - `class Type` + Compacts the current context. Must be the final input item. - An action to type in text. + - `type: :compaction_trigger` - - `class Wait` + The type of the item. Always `compaction_trigger`. - A wait action. + - `:compaction_trigger` - `agent: Agent{ agent_name}` @@ -66983,58 +77326,51 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput` - - The output of a computer tool call. - - - `call_id: String` - - The ID of the computer tool call that produced the output. - - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `class ItemReference` - A computer screenshot image used with the computer use tool. + An internal identifier for an item to reference. - - `type: :computer_screenshot` + - `id: String` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The ID of the item to reference. - - `:computer_screenshot` + - `agent: Agent{ agent_name}` - - `file_id: String` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: String` - - `image_url: String` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `type: :item_reference` - - `type: :computer_call_output` + The type of item to reference. Always `item_reference`. - The type of the computer tool call output. Always `computer_call_output`. + - `:item_reference` - - `:computer_call_output` + - `class Program` - `id: String` - The ID of the computer tool call output. + The unique ID of this program item. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `call_id: String` - The safety checks reported by the API that have been acknowledged by the developer. + The stable call ID of the program item. - - `id: String` + - `code: String` - The ID of the pending safety check. + The JavaScript source executed by programmatic tool calling. - - `code: String` + - `fingerprint: String` - The type of the pending safety check. + Opaque program replay fingerprint that must be round-tripped. - - `message: String` + - `type: :program` - Details about the pending safety check. + The item type. Always `program`. + + - `:program` - `agent: Agent{ agent_name}` @@ -67044,319 +77380,333 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `class ProgramOutput` - 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 this program output item. - - `:completed` + - `call_id: String` - - `:incomplete` + The call ID of the program item. - - `class BetaResponseFunctionWebSearch` + - `result: 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 result produced by the program item. - - `id: String` + - `status: :completed | :incomplete` - The unique ID of the web search tool call. + The terminal status of the program output. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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` - - `class Search` + - `type: :program_output` - Action type "search" - Performs a web search query. + The item type. Always `program_output`. - - `type: :search` + - `:program_output` - The action type. + - `agent: Agent{ agent_name}` - - `:search` + The agent that produced this item. - - `queries: Array[String]` + - `agent_name: String` - The search queries. + The canonical name of the agent that produced this item. - - `query: String` + - `metadata: Hash[Symbol, String]` - The search query. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `sources: Array[Source{ type, url}]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The sources used in the search. + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - - `type: :url` + 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 source. Always `url`. + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - - `:url` + 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. - - `url: String` + - `:"gpt-5.6-sol"` - The URL of the source. + - `:"gpt-5.6-terra"` - - `class OpenPage` + - `:"gpt-5.6-luna"` - Action type "open_page" - Opens a specific URL from search results. + - `:"gpt-5.4"` - - `type: :open_page` + - `:"gpt-5.4-mini"` - The action type. + - `:"gpt-5.4-nano"` - - `:open_page` + - `:"gpt-5.4-mini-2026-03-17"` - - `url: String` + - `:"gpt-5.4-nano-2026-03-17"` - The URL opened by the model. + - `:"gpt-5.3-chat-latest"` - - `class FindInPage` + - `:"gpt-5.2"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `:"gpt-5.2-2025-12-11"` - - `pattern: String` + - `:"gpt-5.2-chat-latest"` - The pattern or text to search for within the page. + - `:"gpt-5.2-pro"` - - `type: :find_in_page` + - `:"gpt-5.2-pro-2025-12-11"` - The action type. + - `:"gpt-5.1"` - - `:find_in_page` + - `:"gpt-5.1-2025-11-13"` - - `url: String` + - `:"gpt-5.1-codex"` - The URL of the page searched for the pattern. + - `:"gpt-5.1-mini"` - - `status: :in_progress | :searching | :completed | :failed` + - `:"gpt-5.1-chat-latest"` - The status of the web search tool call. + - `:"gpt-5"` - - `:in_progress` + - `:"gpt-5-mini"` - - `:searching` + - `:"gpt-5-nano"` - - `:completed` + - `:"gpt-5-2025-08-07"` - - `:failed` + - `:"gpt-5-mini-2025-08-07"` - - `type: :web_search_call` + - `:"gpt-5-nano-2025-08-07"` - The type of the web search tool call. Always `web_search_call`. + - `:"gpt-5-chat-latest"` - - `:web_search_call` + - `:"gpt-4.1"` - - `agent: Agent{ agent_name}` + - `:"gpt-4.1-mini"` - The agent that produced this item. + - `:"gpt-4.1-nano"` - - `agent_name: String` + - `:"gpt-4.1-2025-04-14"` - The canonical name of the agent that produced this item. + - `:"gpt-4.1-mini-2025-04-14"` - - `class BetaResponseFunctionToolCall` + - `:"gpt-4.1-nano-2025-04-14"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `:"o4-mini"` - - `arguments: String` + - `:"o4-mini-2025-04-16"` - A JSON string of the arguments to pass to the function. + - `:o3` - - `call_id: String` + - `:"o3-2025-04-16"` - The unique ID of the function tool call generated by the model. + - `:"o3-mini"` - - `name: String` + - `:"o3-mini-2025-01-31"` - The name of the function to run. + - `:o1` - - `type: :function_call` + - `:"o1-2024-12-17"` - The type of the function tool call. Always `function_call`. + - `:"o1-preview"` - - `:function_call` + - `:"o1-preview-2024-09-12"` - - `id: String` + - `:"o1-mini"` - The unique ID of the function tool call. + - `:"o1-mini-2024-09-12"` - - `agent: Agent{ agent_name}` + - `:"gpt-4o"` - The agent that produced this item. + - `:"gpt-4o-2024-11-20"` - - `agent_name: String` + - `:"gpt-4o-2024-08-06"` - The canonical name of the agent that produced this item. + - `:"gpt-4o-2024-05-13"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-4o-audio-preview"` - The execution context that produced this tool call. + - `:"gpt-4o-audio-preview-2024-10-01"` - - `class Direct` + - `:"gpt-4o-audio-preview-2024-12-17"` - - `type: :direct` + - `:"gpt-4o-audio-preview-2025-06-03"` - - `:direct` + - `:"gpt-4o-mini-audio-preview"` - - `class Program` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - - `caller_id: String` + - `:"gpt-4o-search-preview"` - The call ID of the program item that produced this tool call. + - `:"gpt-4o-mini-search-preview"` - - `type: :program` + - `:"gpt-4o-search-preview-2025-03-11"` - - `:program` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - - `namespace: String` + - `:"chatgpt-4o-latest"` - The namespace of the function to run. + - `:"codex-mini-latest"` - - `status: :in_progress | :completed | :incomplete` + - `:"gpt-4o-mini"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:"gpt-4o-mini-2024-07-18"` - - `:in_progress` + - `:"gpt-4-turbo"` - - `:completed` + - `:"gpt-4-turbo-2024-04-09"` - - `:incomplete` + - `:"gpt-4-0125-preview"` - - `class FunctionCallOutput` + - `:"gpt-4-turbo-preview"` - The output of a function tool call. + - `:"gpt-4-1106-preview"` - - `call_id: String` + - `:"gpt-4-vision-preview"` - The unique ID of the function tool call generated by the model. + - `:"gpt-4"` - - `output: String | BetaResponseFunctionCallOutputItemList` + - `:"gpt-4-0314"` - Text, image, or file output of the function tool call. + - `:"gpt-4-0613"` - - `String = String` + - `:"gpt-4-32k"` - A JSON string of the output of the function tool call. + - `:"gpt-4-32k-0314"` - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `:"gpt-4-32k-0613"` - An array of content outputs (text, image, file) for the function tool call. + - `:"gpt-3.5-turbo"` - - `class BetaResponseInputTextContent` + - `:"gpt-3.5-turbo-16k"` - A text input to the model. + - `:"gpt-3.5-turbo-0301"` - - `text: String` + - `:"gpt-3.5-turbo-0613"` - The text input to the model. + - `:"gpt-3.5-turbo-1106"` - - `type: :input_text` + - `:"gpt-3.5-turbo-0125"` - The type of the input item. Always `input_text`. + - `:"gpt-3.5-turbo-16k-0613"` - - `:input_text` + - `:"o1-pro"` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"o1-pro-2025-03-19"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:"o3-pro"` - - `mode: :explicit` + - `:"o3-pro-2025-06-10"` - The breakpoint mode. Always `explicit`. + - `:"o3-deep-research"` - - `:explicit` + - `:"o3-deep-research-2025-06-26"` - - `class BetaResponseInputImageContent` + - `:"o4-mini-deep-research"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:"o4-mini-deep-research-2025-06-26"` - - `type: :input_image` + - `:"computer-use-preview"` - The type of the input item. Always `input_image`. + - `:"computer-use-preview-2025-03-11"` - - `:input_image` + - `:"gpt-5-codex"` - - `detail: :low | :high | :auto | :original` + - `:"gpt-5-pro"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:"gpt-5-pro-2025-10-06"` - - `:low` + - `:"gpt-5.1-codex-max"` - - `:high` + - `String = String` - - `:auto` + - `object: :response` - - `:original` + The object type of this resource - always set to `response`. - - `file_id: String` + - `:response` - The ID of the file to be sent to the model. + - `output: Array[BetaResponseOutputItem]` - - `image_url: String` + An array of content items generated by the model. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - 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. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class BetaResponseOutputMessage` - Marks the exact end of a reusable 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 output message from the model. - - `mode: :explicit` + - `class BetaResponseFileSearchToolCall` - The breakpoint mode. Always `explicit`. + 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. - - `:explicit` + - `class BetaResponseFunctionToolCall` - - `class BetaResponseInputFileContent` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - A file input to the model. + - `class BetaResponseFunctionToolCallOutputItem` - - `type: :input_file` + - `id: String` - The type of the input item. Always `input_file`. + The unique ID of the function call tool output. - - `:input_file` + - `call_id: String` - - `detail: :auto | :low | :high` + The unique ID of the function tool call generated by 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`. + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:auto` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:low` + - `String = String` - - `:high` + A string of the output of the function call. - - `file_data: String` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The base64-encoded data of the file to be sent to the model. + Text, image, or file output of the function call. - - `file_id: String` + - `class BetaResponseInputText` - The ID of the file to be sent to the model. + A text input to the model. - - `file_url: String` + - `class BetaResponseInputImage` - The URL of the file to be sent to the model. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `filename: String` + - `class BetaResponseInputFile` - The name of the file to be sent to the model. + A file input to the model. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `status: :in_progress | :completed | :incomplete` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `mode: :explicit` + - `:in_progress` - The breakpoint mode. Always `explicit`. + - `:completed` - - `:explicit` + - `:incomplete` - `type: :function_call_output` @@ -67364,10 +77714,6 @@ puts(beta_compacted_response) - `:function_call_output` - - `id: String` - - The unique ID of the function tool call output. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -67400,35 +77746,121 @@ puts(beta_compacted_response) - `:program` - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` + - `created_by: String` - - `:incomplete` + The identifier of the actor that created the item. - `class AgentMessage` - A message routed between agents. + - `id: String` + + The unique ID of the agent message. - `author: String` The sending agent identity. - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - Plaintext, image, or encrypted content sent between agents. + Encrypted content sent between agents. - - `class BetaResponseInputTextContent` + - `class BetaResponseInputText` A text input to the model. - - `class BetaResponseInputImageContent` + - `class BetaResponseOutputText` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A text output from the model. + + - `class Text` + + A text content. + + - `text: String` + + - `type: :text` + + - `:text` + + - `class SummaryText` + + 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` + + - `class ReasoningText` + + 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` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot` + + A screenshot of a computer. + + - `detail: :low | :high | :auto | :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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. - `class EncryptedContent` @@ -67450,14 +77882,10 @@ puts(beta_compacted_response) - `type: :agent_message` - The item type. Always `agent_message`. + The type of the item. Always `agent_message`. - `:agent_message` - - `id: String` - - The unique ID of this agent message item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -67468,9 +77896,13 @@ puts(beta_compacted_response) - `class MultiAgentCall` + - `id: String` + + The unique ID of the multi-agent call item. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The multi-agent action that was executed. + The multi-agent action to execute. - `:spawn_agent` @@ -67486,7 +77918,7 @@ puts(beta_compacted_response) - `arguments: String` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `call_id: String` @@ -67494,14 +77926,10 @@ puts(beta_compacted_response) - `type: :multi_agent_call` - The item type. Always `multi_agent_call`. + The type of the multi-agent call. Always `multi_agent_call`. - `:multi_agent_call` - - `id: String` - - The unique ID of this multi-agent call. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -67512,6 +77940,10 @@ puts(beta_compacted_response) - `class MultiAgentCallOutput` + - `id: String` + + The unique ID of the multi-agent call output item. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` The multi-agent action that produced this result. @@ -67532,105 +77964,140 @@ puts(beta_compacted_response) The unique ID of the multi-agent call. - - `output: Array[Output{ text, type, annotations}]` + - `output: Array[BetaResponseOutputText]` Text output returned by the multi-agent action. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + - `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` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `type: :multi_agent_call_output` - Citations associated with the text content. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `:multi_agent_call_output` - - `file_id: String` + - `agent: Agent{ agent_name}` - The ID of the file. + The agent that produced this item. - - `filename: String` + - `agent_name: String` - The filename of the file cited. + The canonical name of the agent that produced this item. - - `index: Integer` + - `class BetaResponseFunctionWebSearch` - The index of the file in the list of files. + 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: :file_citation` + - `class BetaResponseComputerToolCall` - The citation type. Always `file_citation`. + 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. - - `:file_citation` + - `class BetaResponseComputerToolCallOutputItem` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `id: String` - - `end_index: Integer` + The unique ID of the computer call tool output. - The index of the last character of the citation in the message. + - `call_id: String` - - `start_index: Integer` + The ID of the computer tool call that produced the output. - The index of the first character of the citation in the message. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `title: String` + A computer screenshot image used with the computer use tool. - The title of the cited resource. + - `status: :completed | :incomplete | :failed | :in_progress` - - `type: :url_citation` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The citation type. Always `url_citation`. + - `:completed` - - `:url_citation` + - `:incomplete` - - `url: String` + - `:failed` - The URL of the cited resource. + - `:in_progress` - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `type: :computer_call_output` - - `container_id: String` + The type of the computer tool call output. Always `computer_call_output`. - The ID of the container. + - `:computer_call_output` - - `end_index: Integer` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The index of the last character of the citation in the message. + The safety checks reported by the API that have been acknowledged by the + developer. - - `file_id: String` + - `id: String` - The ID of the container file. + The ID of the pending safety check. - - `filename: String` + - `code: String` - The filename of the container file cited. + The type of the pending safety check. - - `start_index: Integer` + - `message: String` - The index of the first character of the citation in the message. + Details about the pending safety check. - - `type: :container_file_citation` + - `agent: Agent{ agent_name}` - The citation type. Always `container_file_citation`. + The agent that produced this item. - - `:container_file_citation` + - `agent_name: String` - - `type: :multi_agent_call_output` + The canonical name of the agent that produced this item. - The item type. Always `multi_agent_call_output`. + - `created_by: String` - - `:multi_agent_call_output` + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem` + + 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). + + - `class Program` - `id: String` - The unique ID of this multi-agent call output. + 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: Agent{ agent_name}` @@ -67640,21 +78107,33 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall` + - `class ProgramOutput` - - `arguments: untyped` + - `id: String` - The arguments supplied to the tool search call. + The unique ID of the program output item. - - `type: :tool_search_call` + - `call_id: String` - The item type. Always `tool_search_call`. + The call ID of the program item. - - `:tool_search_call` + - `result: String` - - `id: String` + The result produced by the program item. - The unique ID of this tool search call. + - `status: :completed | :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: Agent{ agent_name}` @@ -67664,6 +78143,16 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. + - `class BetaResponseToolSearchCall` + + - `id: String` + + The unique ID of the tool search call item. + + - `arguments: untyped` + + Arguments used for the tool search call. + - `call_id: String` The unique ID of the tool search call generated by the model. @@ -67678,7 +78167,7 @@ puts(beta_compacted_response) - `status: :in_progress | :completed | :incomplete` - The status of the tool search call. + The status of the tool search call item that was recorded. - `:in_progress` @@ -67686,1149 +78175,1206 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseToolSearchOutputItemParam` + - `type: :tool_search_call` + + The type of the item. Always `tool_search_call`. + + - `:tool_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` + + - `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 | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output item that was recorded. + + - `:in_progress` + + - `:completed` + + - `:incomplete` - `tools: Array[BetaTool]` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool` 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` + - `class BetaFileSearchTool` - The name of the function to 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). - - `parameters: Hash[Symbol, untyped]` + - `class BetaComputerTool` - A JSON schema object describing the parameters of the function. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `strict: bool` + - `class BetaComputerUsePreviewTool` - Whether strict parameter validation is enforced for this function tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :function` + - `class BetaWebSearchTool` - The type of the function tool. Always `function`. + 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). - - `:function` + - `class Mcp` - - `allowed_callers: Array[:direct | :programmatic]` + 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 tool invocation context(s). + - `class CodeInterpreter` - - `:direct` + A tool that runs Python code to help generate a response to a prompt. - - `:programmatic` + - `class ProgrammaticToolCalling` - - `defer_loading: bool` + - `class ImageGeneration` - Whether this function is deferred and loaded via tool search. + A tool that generates images using the GPT image models. - - `description: String` + - `class LocalShell` - A description of the function. Used by the model to determine whether or not to call the function. + A tool that allows the model to execute shell commands in a local environment. - - `output_schema: Hash[Symbol, untyped]` + - `class BetaFunctionShellTool` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A tool that allows the model to execute shell commands. - - `class BetaFileSearchTool` + - `class BetaCustomTool` - 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 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: :file_search` + - `class BetaNamespaceTool` - The type of the file search tool. Always `file_search`. + Groups function/custom tools under a shared namespace. - - `:file_search` + - `class BetaToolSearchTool` - - `vector_store_ids: Array[String]` + Hosted or BYOT tool search configuration for deferred tools. - The IDs of the vector stores to search. + - `class BetaWebSearchPreviewTool` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, 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 filter to apply. + - `class BetaApplyPatchTool` - - `class ComparisonFilter` + Allows the assistant to create, delete, or update files using unified diffs. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: :tool_search_output` - - `key: String` + The type of the item. Always `tool_search_output`. - The key to compare against the value. + - `:tool_search_output` - - `type: :eq | :ne | :gt | 5 more` + - `agent: Agent{ 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` + - `created_by: String` - - `:gt` + The identifier of the actor that created the item. - - `:gte` + - `class AdditionalTools` - - `:lt` + - `id: String` - - `:lte` + The unique ID of the additional tools item. - - `:in` + - `role: :unknown | :user | :assistant | 5 more` - - `:nin` + The role that provided the additional tools. - - `value: String | Float | bool | Array[untyped]` + - `:unknown` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:user` - - `String = String` + - `:assistant` - - `Float = Float` + - `:system` - - `UnionMember2 = bool` + - `:critic` - - `UnionMember3 = Array[untyped]` + - `:discriminator` - - `class CompoundFilter` + - `:developer` - Combine multiple filters using `and` or `or`. + - `:tool` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + - `tools: Array[BetaTool]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The additional tool definitions made available at this item. - - `class ComparisonFilter` + - `class BetaFunctionTool` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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). - - `key: String` + - `class BetaFileSearchTool` - The key to compare against the value. + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. - - `type: :eq | :ne | :gt | 5 more` + - `class LocalShell` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool that allows the model to execute shell commands in a local environment. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class BetaFunctionShellTool` - - `:eq` + A tool that allows the model to execute shell commands. - - `:ne` + - `class BetaCustomTool` - - `:gt` + 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) - - `:gte` + - `class BetaNamespaceTool` - - `:lt` + Groups function/custom tools under a shared namespace. - - `:lte` + - `class BetaToolSearchTool` - - `:in` + Hosted or BYOT tool search configuration for deferred tools. - - `:nin` + - `class BetaWebSearchPreviewTool` - - `value: String | Float | bool | Array[untyped]` + 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 value to compare against the attribute key; supports string, number, or boolean types. + - `class BetaApplyPatchTool` - - `String = String` + Allows the assistant to create, delete, or update files using unified diffs. - - `Float = Float` + - `type: :additional_tools` - - `UnionMember2 = bool` + The type of the item. Always `additional_tools`. - - `UnionMember3 = Array[untyped]` + - `:additional_tools` - - `UnionMember1 = untyped` + - `agent: Agent{ agent_name}` - - `type: :and | :or` + The agent that produced this item. - Type of operation: `and` or `or`. + - `agent_name: String` - - `:and` + The canonical name of the agent that produced this item. - - `:or` + - `class BetaResponseCompactionItem` - - `max_num_results: Integer` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `id: String` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + The unique ID of the compaction item. - Ranking options for search. + - `encrypted_content: String` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + The encrypted content that was produced by compaction. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: :compaction` - - `embedding_weight: Float` + The type of the item. Always `compaction`. - The weight of the embedding in the reciprocal ranking fusion. + - `:compaction` - - `text_weight: Float` + - `agent: Agent{ agent_name}` - The weight of the text in the reciprocal ranking fusion. + The agent that produced this item. - - `ranker: :auto | :"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` + - `created_by: String` - - `:"default-2024-11-15"` + The identifier of the actor that created the item. - - `score_threshold: Float` + - `class ImageGenerationCall` - 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 image generation request made by the model. - - `class BetaComputerTool` + - `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 image generation call. - - `type: :computer` + - `result: String` - The type of the computer tool. Always `computer`. + The generated image encoded in base64. - - `:computer` + - `status: :in_progress | :completed | :generating | :failed` - - `class BetaComputerUsePreviewTool` + The status of the image generation 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: Integer` + - `:completed` - The height of the computer display. + - `:generating` - - `display_width: Integer` + - `:failed` - The width of the computer display. + - `type: :image_generation_call` - - `environment: :windows | :mac | :linux | 2 more` + The type of the image generation call. Always `image_generation_call`. - The type of computer environment to control. + - `:image_generation_call` - - `:windows` + - `agent: Agent{ agent_name}` - - `:mac` + The agent that produced this item. - - `:linux` + - `agent_name: String` - - `:ubuntu` + The canonical name of the agent that produced this item. - - `:browser` + - `class BetaResponseCodeInterpreterToolCall` - - `type: :computer_use_preview` + A tool call to run code. - The type of the computer use tool. Always `computer_use_preview`. + - `class LocalShellCall` - - `:computer_use_preview` + A tool call to run a command on the local shell. - - `class BetaWebSearchTool` + - `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 local shell call. - - `type: :web_search | :web_search_2025_08_26` + - `action: Action{ command, env, type, 3 more}` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Execute a shell command on the server. - - `:web_search` + - `command: Array[String]` - - `:web_search_2025_08_26` + The command to run. - - `filters: Filters{ allowed_domains}` + - `env: Hash[Symbol, String]` - Filters for the search. + Environment variables to set for the command. - - `allowed_domains: Array[String]` + - `type: :exec` - 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 local shell action. Always `exec`. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `:exec` - - `search_context_size: :low | :medium | :high` + - `timeout_ms: Integer` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Optional timeout in milliseconds for the command. - - `:low` + - `user: String` - - `:medium` + Optional user to run the command as. - - `:high` + - `working_directory: String` - - `user_location: UserLocation{ city, country, region, 2 more}` + Optional working directory to run the command in. - The approximate location of the user. + - `call_id: String` - - `city: String` + The unique ID of the local shell tool call generated by the model. - Free text input for the city of the user, e.g. `San Francisco`. + - `status: :in_progress | :completed | :incomplete` - - `country: String` + The status of the local shell call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `:in_progress` - - `region: String` + - `:completed` - Free text input for the region of the user, e.g. `California`. + - `:incomplete` - - `timezone: String` + - `type: :local_shell_call` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the local shell call. Always `local_shell_call`. - - `type: :approximate` + - `:local_shell_call` - The type of location approximation. Always `approximate`. + - `agent: Agent{ agent_name}` - - `:approximate` + The agent that produced this item. - - `class Mcp` + - `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` + - `class LocalShellCallOutput` - A label for this MCP server, used to identify it in tool calls. + The output of a local shell tool call. - - `type: :mcp` + - `id: String` - The type of the MCP tool. Always `mcp`. + The unique ID of the local shell tool call generated by the model. - - `:mcp` + - `output: String` - - `allowed_callers: Array[:direct | :programmatic]` + A JSON string of the output of the local shell tool call. - The tool invocation context(s). + - `type: :local_shell_call_output` - - `:direct` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:programmatic` + - `:local_shell_call_output` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `agent: Agent{ agent_name}` - List of allowed tool names or a filter object. + The agent that produced this item. - - `McpAllowedTools = Array[String]` + - `agent_name: String` - A string array of allowed tool names + The canonical name of the agent that produced this item. - - `class McpToolFilter` + - `status: :in_progress | :completed | :incomplete` - A filter object to specify which tools are allowed. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `read_only: bool` + - `: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: Array[String]` + - `:incomplete` - List of allowed tool names. + - `class BetaResponseFunctionShellToolCall` - - `authorization: String` + A tool call that executes one or more shell commands in a managed environment. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `id: String` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + The unique ID of the shell tool call. Populated when this item is returned via API. - 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). + - `action: Action{ commands, max_output_length, timeout_ms}` - Currently supported `connector_id` values are: + The shell commands and limits that describe how to run 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` + - `commands: Array[String]` - - `:connector_dropbox` + - `max_output_length: Integer` - - `:connector_gmail` + Optional maximum number of characters to return from each command. - - `:connector_googlecalendar` + - `timeout_ms: Integer` - - `:connector_googledrive` + Optional timeout in milliseconds for the commands. - - `:connector_microsoftteams` + - `call_id: String` - - `:connector_outlookcalendar` + The unique ID of the shell tool call generated by the model. - - `:connector_outlookemail` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:connector_sharepoint` + Represents the use of a local environment to perform shell actions. - - `defer_loading: bool` + - `class BetaResponseLocalEnvironment` - Whether this MCP tool is deferred and discovered via tool search. + Represents the use of a local environment to perform shell actions. - - `headers: Hash[Symbol, String]` + - `type: :local` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The environment type. Always `local`. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:local` - Specify which of the MCP server's tools require approval. + - `class BetaResponseContainerReference` - - `class McpToolApprovalFilter` + Represents a container created with /v1/containers. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `container_id: String` - - `always: Always{ read_only, tool_names}` + - `type: :container_reference` - A filter object to specify which tools are allowed. + The environment type. Always `container_reference`. - - `read_only: bool` + - `: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. + - `status: :in_progress | :completed | :incomplete` - - `tool_names: Array[String]` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - List of allowed tool names. + - `:in_progress` - - `never: Never{ read_only, tool_names}` + - `:completed` - A filter object to specify which tools are allowed. + - `:incomplete` - - `read_only: bool` + - `type: :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. + The type of the item. Always `shell_call`. - - `tool_names: Array[String]` + - `:shell_call` - List of allowed tool names. + - `agent: Agent{ agent_name}` - - `McpToolApprovalSetting = :always | :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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `server_description: String` + The execution context that produced this tool call. - Optional description of the MCP server, used to provide more context. + - `class Direct` - - `server_url: String` + - `type: :direct` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:direct` - - `tunnel_id: String` + - `class 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. + - `caller_id: String` - - `class CodeInterpreter` + The call ID of the program item that produced this tool call. - A tool that runs Python code to help generate a response to a prompt. + - `type: :program` - - `container: String | CodeInterpreterToolAuto{ 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. + - `created_by: String` - - `String = String` + The ID of the entity that created this tool call. - The container ID. + - `class BetaResponseFunctionShellToolCallOutput` - - `class CodeInterpreterToolAuto` + The output of a shell tool call that was emitted. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `id: String` - - `type: :auto` + The unique ID of the shell call output. Populated when this item is returned via API. - Always `auto`. + - `call_id: String` - - `:auto` + The unique ID of the shell tool call generated by the model. - - `file_ids: Array[String]` + - `max_output_length: Integer` - An optional list of uploaded files to make available to your code. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - The memory limit for the code interpreter container. + An array of shell call output contents - - `:"1g"` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `:"4g"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `:"16g"` + - `class Timeout` - - `:"64g"` + Indicates that the shell call exceeded its configured time limit. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :timeout` - Network access policy for the container. + The outcome type. Always `timeout`. - - `class BetaContainerNetworkPolicyDisabled` + - `:timeout` - - `type: :disabled` + - `class Exit` - Disable outbound network access. Always `disabled`. + Indicates that the shell commands finished and returned an exit code. - - `:disabled` + - `exit_code: Integer` - - `class BetaContainerNetworkPolicyAllowlist` + Exit code from the shell process. - - `allowed_domains: Array[String]` + - `type: :exit` - A list of allowed domains when type is `allowlist`. + The outcome type. Always `exit`. - - `type: :allowlist` + - `:exit` - Allow outbound network access only to specified domains. Always `allowlist`. + - `stderr: String` - - `:allowlist` + The standard error output that was captured. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `stdout: String` - Optional domain-scoped secrets for allowlisted domains. + The standard output that was captured. - - `domain: String` + - `created_by: String` - The domain associated with the secret. + The identifier of the actor that created the item. - - `name: String` + - `status: :in_progress | :completed | :incomplete` - The name of the secret to inject for the domain. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `value: String` + - `:in_progress` - The secret value to inject for the domain. + - `:completed` - - `type: :code_interpreter` + - `:incomplete` - The type of the code interpreter tool. Always `code_interpreter`. + - `type: :shell_call_output` - - `:code_interpreter` + The type of the shell call output. Always `shell_call_output`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:shell_call_output` - The tool invocation context(s). + - `agent: Agent{ agent_name}` - - `:direct` + The agent that produced this item. - - `:programmatic` + - `agent_name: String` - - `class ProgrammaticToolCalling` + The canonical name of the agent that produced this item. - - `type: :programmatic_tool_calling` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The type of the tool. Always `programmatic_tool_calling`. + The execution context that produced this tool call. - - `:programmatic_tool_calling` + - `class Direct` - - `class ImageGeneration` + - `type: :direct` - A tool that generates images using the GPT image models. + - `:direct` - - `type: :image_generation` + - `class Program` - The type of the image generation tool. Always `image_generation`. + - `caller_id: String` - - `:image_generation` + The call ID of the program item that produced this tool call. - - `action: :generate | :edit | :auto` + - `type: :program` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `:program` - - `:generate` + - `created_by: String` - - `:edit` + The identifier of the actor that created the item. - - `:auto` + - `class BetaResponseApplyPatchToolCall` - - `background: :transparent | :opaque | :auto` + A tool call that applies file diffs by creating, deleting, or updating files. - 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 unique ID of the apply patch tool call. Populated when this item is returned via API. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `call_id: String` - - `:transparent` + The unique ID of the apply patch tool call generated by the model. - - `:opaque` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `:auto` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `input_fidelity: :high | :low` + - `class CreateFile` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Instruction describing how to create a file via the apply_patch tool. - - `:high` + - `diff: String` - - `:low` + Diff to apply. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `path: String` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Path of the file to create. - - `file_id: String` + - `type: :create_file` - File ID for the mask image. + Create a new file with the provided diff. - - `image_url: String` + - `:create_file` - Base64-encoded mask image. + - `class DeleteFile` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + Instruction describing how to delete a file via the apply_patch tool. - The image generation model to use. Default: `gpt-image-1`. + - `path: String` - - `String = String` + Path of the file to delete. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `type: :delete_file` - The image generation model to use. Default: `gpt-image-1`. + Delete the specified file. - - `:"gpt-image-1"` + - `:delete_file` - - `:"gpt-image-1-mini"` + - `class UpdateFile` - - `:"gpt-image-2"` + Instruction describing how to update a file via the apply_patch tool. - - `:"gpt-image-2-2026-04-21"` + - `diff: String` - - `:"gpt-image-1.5"` + Diff to apply. - - `:"chatgpt-image-latest"` + - `path: String` - - `moderation: :auto | :low` + Path of the file to update. - Moderation level for the generated image. Default: `auto`. + - `type: :update_file` - - `:auto` + Update an existing file with the provided diff. - - `:low` + - `:update_file` - - `output_compression: Integer` + - `status: :in_progress | :completed` - Compression level for the output image. Default: 100. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `output_format: :png | :webp | :jpeg` + - `:in_progress` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `:completed` - - `:png` + - `type: :apply_patch_call` - - `:webp` + The type of the item. Always `apply_patch_call`. - - `:jpeg` + - `:apply_patch_call` - - `partial_images: Integer` + - `agent: Agent{ agent_name}` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The agent that produced this item. - - `quality: :low | :medium | :high | :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_: Direct{ type} | Program{ caller_id, type}` - - `:medium` + The execution context that produced this tool call. - - `:high` + - `class Direct` - - `:auto` + - `type: :direct` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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`. + - `class Program` - - `String = String` + - `caller_id: String` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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"` + - `:program` - - `:"1024x1536"` + - `created_by: String` - - `:"1536x1024"` + The ID of the entity that created this tool call. - - `:auto` + - `class BetaResponseApplyPatchToolCallOutput` - - `class LocalShell` + The output emitted by an apply patch tool call. - A tool that allows the model to execute shell commands in a local environment. + - `id: String` - - `type: :local_shell` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The type of the local shell tool. Always `local_shell`. + - `call_id: String` - - `:local_shell` + The unique ID of the apply patch tool call generated by the model. - - `class BetaFunctionShellTool` + - `status: :completed | :failed` - A tool that allows the model to execute shell commands. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: :shell` + - `:completed` - The type of the shell tool. Always `shell`. + - `:failed` - - `:shell` + - `type: :apply_patch_call_output` - - `allowed_callers: Array[:direct | :programmatic]` + The type of the item. Always `apply_patch_call_output`. - The tool invocation context(s). + - `:apply_patch_call_output` - - `:direct` + - `agent: Agent{ agent_name}` - - `:programmatic` + The agent that produced this item. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `agent_name: String` - - `class BetaContainerAuto` + The canonical name of the agent that produced this item. - - `type: :container_auto` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Automatically creates a container for this request + The execution context that produced this tool call. - - `:container_auto` + - `class Direct` - - `file_ids: Array[String]` + - `type: :direct` - An optional list of uploaded files to make available to your code. + - `:direct` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class Program` - The memory limit for the container. + - `caller_id: String` - - `:"1g"` + The call ID of the program item that produced this tool call. - - `:"4g"` + - `type: :program` - - `:"16g"` + - `:program` - - `:"64g"` + - `created_by: String` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + The ID of the entity that created this tool call output. - Network access policy for the container. + - `output: String` - - `class BetaContainerNetworkPolicyDisabled` + Optional textual output returned by the apply patch tool. - - `class BetaContainerNetworkPolicyAllowlist` + - `class McpCall` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + An invocation of a tool on an MCP server. - An optional list of skills referenced by id or inline data. + - `id: String` - - `class BetaSkillReference` + The unique ID of the tool call. - - `skill_id: String` + - `arguments: String` - The ID of the referenced skill. + A JSON string of the arguments passed to the tool. - - `type: :skill_reference` + - `name: String` - References a skill created with the /v1/skills endpoint. + The name of the tool that was run. - - `:skill_reference` + - `server_label: String` - - `version: String` + The label of the MCP server running the tool. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: :mcp_call` - - `class BetaInlineSkill` + The type of the item. Always `mcp_call`. - - `description: String` + - `:mcp_call` - The description of the skill. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the skill. + - `agent_name: String` - - `source: BetaInlineSkillSource` + The canonical name of the agent that produced this item. - Inline skill payload + - `approval_request_id: String` - - `data: 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. - Base64-encoded skill zip bundle. + - `error: String` - - `media_type: :"application/zip"` + The error from the tool call, if any. - The media type of the inline skill payload. Must be `application/zip`. + - `output: String` - - `:"application/zip"` + The output from the tool call. - - `type: :base64` + - `status: :in_progress | :completed | :incomplete | 2 more` - The type of the inline skill source. Must be `base64`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `:base64` + - `:in_progress` - - `type: :inline` + - `:completed` - Defines an inline skill for this request. + - `:incomplete` - - `:inline` + - `:calling` - - `class BetaLocalEnvironment` + - `:failed` - - `type: :local` + - `class McpListTools` - Use a local computer environment. + A list of tools available on an MCP server. - - `:local` + - `id: String` - - `skills: Array[BetaLocalSkill]` + The unique ID of the list. - An optional list of skills. + - `server_label: String` - - `description: String` + The label of the MCP server. - The description of the skill. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `name: String` + The tools available on the server. - The name of the skill. + - `input_schema: untyped` - - `path: String` + The JSON schema describing the tool's input. - The path to the directory containing the skill. + - `name: String` - - `class BetaContainerReference` + The name of the tool. - - `container_id: String` + - `annotations: untyped` - The ID of the referenced container. + Additional annotations about the tool. - - `type: :container_reference` + - `description: String` - References a container created with the /v1/containers endpoint + The description of the tool. - - `:container_reference` + - `type: :mcp_list_tools` - - `class BetaCustomTool` + The type of the item. Always `mcp_list_tools`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `:mcp_list_tools` - - `name: String` + - `agent: Agent{ 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` + - `error: String` - - `allowed_callers: Array[:direct | :programmatic]` + Error message if the server could not list tools. - The tool invocation context(s). + - `class McpApprovalRequest` - - `:direct` + A request for human approval of a tool invocation. - - `:programmatic` + - `id: String` - - `defer_loading: bool` + The unique ID of the approval request. - Whether this tool should be deferred and discovered via tool search. + - `arguments: String` - - `description: String` + A JSON string of arguments for the tool. - Optional description of the custom tool, used to provide more context. + - `name: String` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + The name of the tool to run. - The input format for the custom tool. Default is unconstrained text. + - `server_label: String` - - `class Text` + The label of the MCP server making the request. - Unconstrained free-form text. + - `type: :mcp_approval_request` - - `type: :text` + The type of the item. Always `mcp_approval_request`. - Unconstrained text format. Always `text`. + - `:mcp_approval_request` - - `:text` + - `agent: Agent{ agent_name}` - - `class Grammar` + 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. + - `class McpApprovalResponse` - - `syntax: :lark | :regex` + A response to an MCP approval request. - The syntax of the grammar definition. One of `lark` or `regex`. + - `id: String` - - `:lark` + The unique ID of the approval response - - `:regex` + - `approval_request_id: String` - - `type: :grammar` + The ID of the approval request being answered. - Grammar format. Always `grammar`. + - `approve: bool` - - `:grammar` + Whether the request was approved. - - `class BetaNamespaceTool` + - `type: :mcp_approval_response` - Groups function/custom tools under a shared namespace. + The type of the item. Always `mcp_approval_response`. - - `description: String` + - `:mcp_approval_response` - A description of the namespace shown to the model. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `agent_name: String` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + The canonical name of the agent that produced this item. - The function/custom tools available inside this namespace. + - `reason: String` - - `class Function` + Optional reason for the decision. - - `name: String` + - `class BetaResponseCustomToolCall` - - `type: :function` + A call to a custom tool created by the model. - - `:function` + - `class BetaResponseCustomToolCallOutputItem` - - `allowed_callers: Array[:direct | :programmatic]` + The output of a custom tool call from your code, being sent back to the model. - The tool invocation context(s). + - `id: String` - - `:direct` + The unique ID of the custom tool call output item. - - `:programmatic` + - `status: :in_progress | :completed | :incomplete` - - `defer_loading: bool` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether this function should be deferred and discovered via tool search. + - `:in_progress` - - `description: String` + - `:completed` - - `output_schema: Hash[Symbol, untyped]` + - `:incomplete` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `created_by: String` - - `parameters: untyped` + The identifier of the actor that created the item. - - `strict: bool` + - `parallel_tool_calls: bool` - 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. + Whether to allow the model to run tool calls in parallel. - - `class BetaCustomTool` + - `temperature: Float` - 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) + 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: :namespace` + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - The type of the tool. Always `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. - - `:namespace` + - `BetaToolChoiceOptions = :none | :auto | :required` - - `class BetaToolSearchTool` + Controls which (if any) tool is called by the model. - Hosted or BYOT tool search configuration for deferred tools. + `none` means the model will not call any tool and instead generates a message. - - `type: :tool_search` + `auto` means the model can pick between generating a message or calling one or + more tools. - The type of the tool. Always `tool_search`. + `required` means the model must call one or more tools. - - `:tool_search` + - `:none` - - `description: String` + - `:auto` - Description shown to the model for a client-executed tool search tool. + - `:required` - - `execution: :server | :client` + - `class BetaToolChoiceAllowed` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `:server` + - `mode: :auto | :required` - - `:client` + Constrains the tools available to the model to a pre-defined set. - - `parameters: untyped` + `auto` allows the model to pick from among the allowed tools and generate a + message. - Parameter schema for a client-executed tool search tool. + `required` requires the model to call one or more of the allowed tools. - - `class BetaWebSearchPreviewTool` + - `:auto` - 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` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `tools: Array[Hash[Symbol, untyped]]` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + A list of tool definitions that the model should be allowed to call. - - `:web_search_preview` + For the Responses API, the list of tool definitions might look like: - - `:web_search_preview_2025_03_11` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `search_content_types: Array[:text | :image]` + - `type: :allowed_tools` - - `:text` + Allowed tool configuration type. Always `allowed_tools`. - - `:image` + - `:allowed_tools` - - `search_context_size: :low | :medium | :high` + - `class BetaToolChoiceTypes` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + 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). - - `:low` + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `:medium` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `:high` + Allowed values are: - - `user_location: UserLocation{ 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: String` + - `:computer_use` - Free text input for the city of the user, e.g. `San Francisco`. + - `:web_search_preview_2025_03_11` - - `country: 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: String` + - `class BetaToolChoiceFunction` - 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: 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. - - `class BetaApplyPatchTool` + - `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`. + - `class BetaToolChoiceMcp` - - `:apply_patch` + Use this option to force the model to call a specific tool on a remote MCP server. - - `allowed_callers: Array[:direct | :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: String` - - `:tool_search_output` + The name of the tool to call on the server. - - `id: String` + - `class BetaToolChoiceCustom` - The unique ID of this tool search output. + Use this option to force the model to call a specific custom tool. - - `agent: Agent{ 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: String` + - `:custom` - The unique ID of the tool search call generated by the model. + - `class BetaSpecificProgrammaticToolCallingParam` - - `execution: :server | :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` + - `class BetaToolChoiceApplyPatch` - - `status: :in_progress | :completed | :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` + - `class BetaToolChoiceShell` - - `class AdditionalTools` + 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[BetaTool]` - 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](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. - `class BetaFunctionTool` @@ -68894,773 +79440,968 @@ puts(beta_compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: :additional_tools` + - `top_p: Float` - The item type. Always `additional_tools`. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `:additional_tools` + We generally recommend altering this or `temperature` but not both. + + - `background: bool` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: Float` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: Conversation{ 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 this additional tools item. + The unique ID of the conversation that this response was associated with. - - `agent: Agent{ agent_name}` + - `max_output_tokens: Integer` - 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: Integer` - 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. - - `class BetaResponseReasoningItem` + - `moderation: Moderation{ input, 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](https://platform.openai.com/docs/guides/conversation-state). + Moderation results for the response input and output, if moderated completions were requested. - - `id: String` + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - The unique identifier of the reasoning content. + Moderation for the response input. - - `summary: Array[Summary{ text, type}]` + - `class ModerationResult` - Reasoning summary content. + A moderation result produced for the response input or output. - - `text: String` + - `categories: Hash[Symbol, bool]` - A summary of the reasoning output from the model so far. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `type: :summary_text` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - The type of the object. Always `summary_text`. + Which modalities of input are reflected by the score for each category. - - `:summary_text` + - `:text` - - `type: :reasoning` + - `:image` - The type of the object. Always `reasoning`. + - `category_scores: Hash[Symbol, Float]` - - `:reasoning` + A dictionary of moderation categories to scores. - - `agent: Agent{ agent_name}` + - `flagged: bool` - 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. - - `content: Array[Content{ text, type}]` + - `type: :moderation_result` - Reasoning text content. + The object type, which was always `moderation_result` for successful moderation results. - - `text: String` + - `:moderation_result` - The reasoning text from the model. + - `class Error` - - `type: :reasoning_text` + An error produced while attempting moderation for the response input or output. - The type of the reasoning text. Always `reasoning_text`. + - `code: String` - - `:reasoning_text` + The error code. - - `encrypted_content: String` + - `message: String` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The error message. - - `status: :in_progress | :completed | :incomplete` + - `type: :error` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The object type, which was always `error` for moderation failures. - - `:in_progress` + - `:error` - - `:completed` + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `:incomplete` + Moderation for the response output. - - `class BetaResponseCompactionItemParam` + - `class ModerationResult` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A moderation result produced for the response input or output. - - `encrypted_content: String` + - `categories: Hash[Symbol, bool]` - The encrypted content of the compaction summary. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `type: :compaction` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - The type of the item. Always `compaction`. + Which modalities of input are reflected by the score for each category. - - `:compaction` + - `:text` - - `id: String` + - `:image` - The ID of the compaction item. + - `category_scores: Hash[Symbol, Float]` - - `agent: Agent{ agent_name}` + A dictionary of moderation categories to scores. - The agent that produced this item. + - `flagged: bool` - - `agent_name: String` + A boolean indicating whether the content was flagged by any category. - The canonical name of the agent that produced this item. + - `model: String` - - `class ImageGenerationCall` + The moderation model that produced this result. - An image generation request made by the model. + - `type: :moderation_result` + + The object type, which was always `moderation_result` for successful moderation results. + + - `:moderation_result` + + - `class Error` + + 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: 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: 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 ID of the image generation call. + The unique identifier of the prompt template to use. - - `result: String` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The generated image encoded in base64. + 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. - - `status: :in_progress | :completed | :generating | :failed` + - `String = String` - The status of the image generation call. + - `class BetaResponseInputText` - - `:in_progress` + A text input to the model. - - `:completed` + - `class BetaResponseInputImage` - - `:generating` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:failed` + - `class BetaResponseInputFile` - - `type: :image_generation_call` + A file input to the model. - The type of the image generation call. Always `image_generation_call`. + - `version: String` - - `:image_generation_call` + Optional version of the prompt template. - - `agent: Agent{ agent_name}` + - `prompt_cache_key: String` - 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). - - `agent_name: String` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - The canonical name of the agent that produced this item. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `class BetaResponseCodeInterpreterToolCall` + - `mode: :implicit | :explicit` - A tool call to run code. + Whether implicit prompt-cache breakpoints were enabled. - - `id: String` + - `:implicit` - The unique ID of the code interpreter tool call. + - `:explicit` - - `code: String` + - `ttl: :"30m"` - The code to run, or null if not available. + The minimum lifetime applied to each cache breakpoint. - - `container_id: String` + - `:"30m"` - The ID of the container used to run the code. + - `prompt_cache_retention: :in_memory | :"24h"` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + Deprecated. Use `prompt_cache_options.ttl` instead. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + 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. - - `class Logs` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The logs output from the code interpreter. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `logs: String` + - `:in_memory` - The logs output from the code interpreter. + - `:"24h"` - - `type: :logs` + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - The type of the output. Always `logs`. + **gpt-5 and o-series models only** - - `:logs` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `class Image` + - `context: :auto | :current_turn | :all_turns` - The image 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. - - `type: :image` + - `:auto` - The type of the output. Always `image`. + - `:current_turn` - - `:image` + - `:all_turns` - - `url: String` + - `effort: :none | :minimal | :low | 4 more` - The URL of the image output from the 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. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `:none` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `:minimal` - - `:in_progress` + - `:low` - - `:completed` + - `:medium` - - `:incomplete` + - `:high` - - `:interpreting` + - `:xhigh` - - `:failed` + - `:max` - - `type: :code_interpreter_call` + - `generate_summary: :auto | :concise | :detailed` - The type of the code interpreter tool call. Always `code_interpreter_call`. + **Deprecated:** use `summary` instead. - - `:code_interpreter_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: Agent{ 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: String | :standard | :pro` - - `class LocalShellCall` + Controls the reasoning execution mode for the request. - A tool call to run a command on the local shell. + When returned on a response, this is the effective execution mode. - - `id: String` + - `String = String` - The unique ID of the local shell call. + - `Mode = :standard | :pro` - - `action: Action{ command, env, type, 3 more}` + Controls the reasoning execution mode for the request. - Execute a shell command on the server. + When returned on a response, this is the effective execution mode. - - `command: Array[String]` + - `:standard` - The command to run. + - `:pro` - - `env: Hash[Symbol, String]` + - `summary: :auto | :concise | :detailed` - Environment variables to set for the command. + 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: :exec` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The type of the local shell action. Always `exec`. + - `:auto` - - `:exec` + - `:concise` - - `timeout_ms: Integer` + - `:detailed` - Optional timeout in milliseconds for the command. + - `safety_identifier: String` - - `user: 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). - Optional user to run the command as. + - `service_tier: :auto | :default | :flex | 2 more` - - `working_directory: String` + Specifies the processing type used for serving the request. - Optional working directory to run the command in. + - 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'. - - `call_id: 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 unique ID of the local shell tool call generated by the model. + - `:auto` - - `status: :in_progress | :completed | :incomplete` + - `:default` - The status of the local shell call. + - `:flex` - - `:in_progress` + - `:scale` + + - `:priority` + + - `status: 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: 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](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `agent: Agent{ agent_name}` + - `format_: 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](https://platform.openai.com/docs/guides/structured-outputs). - The canonical name of the agent that produced this item. + The default format is `{ "type": "text" }` with no additional options. - - `class LocalShellCallOutput` + **Not recommended for gpt-4o and newer models:** - The output of a local shell 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. - - `id: String` + - `class Text` - The unique ID of the local shell tool call generated by the model. + Default response format. Used to generate text responses. - - `output: String` + - `type: :text` - A JSON string of the output of the local shell tool call. + The type of response format being defined. Always `text`. - - `type: :local_shell_call_output` + - `:text` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class BetaResponseFormatTextJSONSchemaConfig` - - `:local_shell_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: Agent{ 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: Hash[Symbol, untyped]` - 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/). - - `status: :in_progress | :completed | :incomplete` + - `type: :json_schema` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The type of response format being defined. Always `json_schema`. - - `:in_progress` + - `:json_schema` - - `:completed` + - `description: String` - - `:incomplete` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class ShellCall` + - `strict: bool` - 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: Action{ commands, max_output_length, timeout_ms}` + - `class JSONObject` - The shell commands and limits that describe how to run the tool call. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `commands: Array[String]` + - `type: :json_object` - Ordered shell commands for the execution environment to run. + The type of response format being defined. Always `json_object`. - - `max_output_length: Integer` + - `:json_object` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `verbosity: :low | :medium | :high` - - `timeout_ms: Integer` + 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`. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `:low` - - `call_id: String` + - `:medium` - The unique ID of the shell tool call generated by the model. + - `:high` - - `type: :shell_call` + - `top_logprobs: Integer` - The type of the item. Always `shell_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. - - `:shell_call` + - `truncation: :auto | :disabled` - - `id: String` + The truncation strategy to use for the model response. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `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: BetaResponseUsage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: Integer` + + The number of input tokens. + + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + + - `cached_tokens: Integer` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: Integer` + + The number of output tokens. + + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: Integer` + + The number of reasoning tokens. + + - `total_tokens: Integer` + + The total number of tokens used. + + - `user: 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: Integer` + + The sequence number of this event. + + - `type: :"response.incomplete"` + + The type of the event. Always `response.incomplete`. + + - `:"response.incomplete"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` +### Beta Response Inject Created Event - The execution context that produced this tool call. +- `class BetaResponseInjectCreatedEvent` - - `class Direct` + Emitted when all injected input items were validated and committed to the + active response. - - `type: :direct` + - `response_id: String` - The caller type. Always `direct`. + The ID of the response that accepted the input. - - `:direct` + - `sequence_number: Integer` - - `class Program` + The sequence number for this event. - - `caller_id: String` + - `type: :"response.inject.created"` - The call ID of the program item that produced this tool call. + The event discriminator. Always `response.inject.created`. - - `type: :program` + - `:"response.inject.created"` - The caller type. Always `program`. + - `stream_id: String` - - `:program` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `environment: BetaLocalEnvironment | BetaContainerReference` +### Beta Response Inject Event - The environment to execute the shell commands in. +- `class BetaResponseInjectEvent` - - `class BetaLocalEnvironment` + 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. - - `class BetaContainerReference` + - `input: Array[BetaResponseInputItem]` - - `status: :in_progress | :completed | :incomplete` + Input items to inject into the active response. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `class BetaEasyInputMessage` - - `:in_progress` + 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. - - `:completed` + - `content: String | BetaResponseInputMessageContentList` - - `:incomplete` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `class ShellCallOutput` + - `String = String` - The streamed output items emitted by a shell tool call. + A text input to the model. - - `call_id: String` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - 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[BetaResponseFunctionShellCallOutputContent]` + - `class BetaResponseInputText` - Captured chunks of stdout and stderr output, along with their associated outcomes. + A text input to the model. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `text: String` - The exit or timeout outcome associated with this shell call. + The text input to the model. - - `class Timeout` + - `type: :input_text` - Indicates that the shell call exceeded its configured time limit. + The type of the input item. Always `input_text`. - - `type: :timeout` + - `:input_text` - The outcome type. Always `timeout`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:timeout` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class Exit` + - `mode: :explicit` - Indicates that the shell commands finished and returned an exit code. + The breakpoint mode. Always `explicit`. - - `exit_code: Integer` + - `:explicit` - The exit code returned by the shell process. + - `class BetaResponseInputImage` - - `type: :exit` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The outcome type. Always `exit`. + - `detail: :low | :high | :auto | :original` - - `:exit` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `stderr: String` + - `:low` - Captured stderr output for the shell call. + - `:high` - - `stdout: String` + - `:auto` - Captured stdout output for the shell call. + - `:original` - - `type: :shell_call_output` + - `type: :input_image` - The type of the item. Always `shell_call_output`. + The type of the input item. Always `input_image`. - - `:shell_call_output` + - `:input_image` - - `id: String` + - `file_id: String` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The ID of the file to be sent to the model. - - `agent: Agent{ agent_name}` + - `image_url: String` - 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. - - `agent_name: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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_: Direct{ type} | Program{ caller_id, type}` + - `mode: :explicit` - The execution context that produced this tool call. + The breakpoint mode. Always `explicit`. - - `class Direct` + - `:explicit` - - `type: :direct` + - `class BetaResponseInputFile` - The caller type. Always `direct`. + A file input to the model. - - `:direct` + - `type: :input_file` - - `class Program` + The type of the input item. Always `input_file`. - - `caller_id: String` + - `:input_file` - The call ID of the program item that produced this tool call. + - `detail: :auto | :low | :high` - - `type: :program` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The caller type. Always `program`. + - `:auto` - - `:program` + - `:low` - - `max_output_length: Integer` + - `:high` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `file_data: String` - - `status: :in_progress | :completed | :incomplete` + The content of the file to be sent to the model. - The status of the shell call output. + - `file_id: String` - - `:in_progress` + The ID of the file to be sent to the model. - - `:completed` + - `file_url: String` - - `:incomplete` + The URL of the file to be sent to the model. - - `class ApplyPatchCall` + - `filename: String` - A tool call representing a request to create, delete, or update files using diff patches. + The name of the file to be sent to the model. - - `call_id: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The unique ID of the apply patch tool call generated by the model. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `mode: :explicit` - The specific create, delete, or update instruction for the apply_patch tool call. + The breakpoint mode. Always `explicit`. - - `class CreateFile` + - `:explicit` - Instruction for creating a new file via the apply_patch tool. + - `role: :user | :assistant | :system | :developer` - - `diff: String` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Unified diff content to apply when creating the file. + - `:user` - - `path: String` + - `:assistant` - Path of the file to create relative to the workspace root. + - `:system` - - `type: :create_file` + - `:developer` - The operation type. Always `create_file`. + - `phase: :commentary | :final_answer` - - `:create_file` + 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. - - `class DeleteFile` + - `:commentary` - Instruction for deleting an existing file via the apply_patch tool. + - `:final_answer` - - `path: String` + - `type: :message` - Path of the file to delete relative to the workspace root. + The type of the message input. Always `message`. - - `type: :delete_file` + - `:message` - The operation type. Always `delete_file`. + - `class Message` - - `:delete_file` + 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. - - `class UpdateFile` + - `content: BetaResponseInputMessageContentList` - Instruction for updating an existing file via the apply_patch tool. + A list of one or many input items to the model, containing different content + types. - - `diff: String` + - `role: :user | :system | :developer` - Unified diff content to apply to the existing file. + The role of the message input. One of `user`, `system`, or `developer`. - - `path: String` + - `:user` - Path of the file to update relative to the workspace root. + - `:system` - - `type: :update_file` + - `:developer` - The operation type. Always `update_file`. + - `agent: Agent{ agent_name}` - - `:update_file` + The agent that produced this item. - - `status: :in_progress | :completed` + - `agent_name: String` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + 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`. + - `type: :message` - - `:apply_patch_call` + The type of the message input. Always set to `message`. + + - `:message` + + - `class BetaResponseOutputMessage` + + An output message from the model. - `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: Agent{ agent_name}` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The agent that produced this item. + The content of the output message. - - `agent_name: String` + - `class BetaResponseOutputText` - The canonical name of the agent that produced this item. + A text output from the model. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - The execution context that produced this tool call. + The annotations of the text output. - - `class Direct` + - `class FileCitation` - - `type: :direct` + A citation to a file. - The caller type. Always `direct`. + - `file_id: String` - - `:direct` + The ID of the file. - - `class Program` + - `filename: String` - - `caller_id: String` + The filename of the file cited. - The call ID of the program item that produced this tool call. + - `index: Integer` - - `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`. - - `class ApplyPatchCallOutput` + - `:file_citation` - The streamed output emitted by an apply patch tool call. + - `class URLCitation` - - `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: Integer` - - `status: :completed | :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: Integer` - - `: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: String` + - `:url_citation` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `url: String` - - `agent: Agent{ agent_name}` + The URL of the web resource. - The agent that produced this item. + - `class ContainerFileCitation` - - `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_: Direct{ type} | Program{ caller_id, type}` + The ID of the container file. - The execution context that produced this tool call. + - `end_index: Integer` - - `class Direct` + 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` - - `class Program` + The filename of the container file cited. - - `caller_id: String` + - `start_index: Integer` - 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: String` + - `class FilePath` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + A path to a file. - - `class McpListTools` + - `file_id: String` - A list of tools available on an MCP server. + The ID of the file. - - `id: String` + - `index: Integer` - 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[Tool{ input_schema, name, annotations, description}]` + - `:file_path` - The tools available on the server. + - `text: String` - - `input_schema: untyped` + The text output from the model. - The JSON schema describing the tool's input. + - `type: :output_text` - - `name: String` + The type of the output text. Always `output_text`. - The name of the tool. + - `:output_text` - - `annotations: untyped` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - Additional annotations about the tool. + - `token: String` - - `description: String` + - `bytes: Array[Integer]` - The description of the tool. + - `logprob: Float` - - `type: :mcp_list_tools` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - The type of the item. Always `mcp_list_tools`. + - `token: String` - - `:mcp_list_tools` + - `bytes: Array[Integer]` - - `agent: Agent{ agent_name}` + - `logprob: Float` - The agent that produced this item. + - `class BetaResponseOutputRefusal` - - `agent_name: String` + A refusal from the model. - The canonical name of the agent that produced this item. + - `refusal: String` - - `error: String` + The refusal explanation from the model. - Error message if the server could not list tools. + - `type: :refusal` - - `class McpApprovalRequest` + 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 | :completed | :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: Agent{ agent_name}` @@ -69670,27 +80411,49 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse` + - `phase: :commentary | :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: bool` + - `class BetaResponseFileSearchToolCall` - Whether the request was approved. + 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: :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[String]` - - `id: String` + The queries used to search for files. - The unique ID of the approval response + - `status: :in_progress | :searching | :completed | 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: Agent{ agent_name}` @@ -69700,60 +80463,73 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `reason: String` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - Optional reason for the decision. + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. 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 = String` + + - `Float = Float` - - `class McpCall` + - `UnionMember2 = bool` - An invocation of a tool on an MCP server. + - `file_id: String` - - `id: String` + The unique ID of the file. - The unique ID of the tool call. + - `filename: String` - - `arguments: String` + The name of the file. - A JSON string of the arguments passed to the tool. + - `score: Float` - - `name: String` + The relevance score of the file - a value between 0 and 1. - The name of the tool that was run. + - `text: String` - - `server_label: String` + The text that was retrieved from the file. - The label of the MCP server running the tool. + - `class BetaResponseComputerToolCall` - - `type: :mcp_call` + 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 type of the item. Always `mcp_call`. + - `id: String` - - `:mcp_call` + The unique ID of the computer call. - - `agent: Agent{ agent_name}` + - `call_id: String` - The agent that produced this item. + An identifier used when responding to the tool call with output. - - `agent_name: String` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - The canonical name of the agent that produced this item. + The pending safety checks for the computer call. - - `approval_request_id: String` + - `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 ID of the pending safety check. - - `error: String` + - `code: String` - The error from the tool call, if any. + The type of the pending safety check. - - `output: String` + - `message: String` - The output from the tool call. + Details about the pending safety check. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `status: :in_progress | :completed | :incomplete` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -69761,242 +80537,247 @@ puts(beta_compacted_response) - `:incomplete` - - `:calling` + - `type: :computer_call` - - `:failed` + The type of the computer call. Always `computer_call`. - - `class BetaResponseCustomToolCallOutput` + - `:computer_call` - The output of a custom tool call from your code, being sent back to the model. + - `action: BetaComputerAction` - - `call_id: String` + A click action. - The call ID, used to map this custom tool call output to a custom tool call. + - `class Click` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | 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 | :right | :wheel | 2 more` - - `String = 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[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:right` - Text, image, or file output of the custom tool call. + - `:wheel` - - `class BetaResponseInputText` + - `:back` - A text input to the model. + - `:forward` - - `class BetaResponseInputImage` + - `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`. - - `class BetaResponseInputFile` + - `:click` - A file input to the model. + - `x: Integer` - - `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_: Integer` - - `:custom_tool_call_output` + The y-coordinate where the click occurred. - - `id: String` + - `keys: Array[String]` - The unique ID of the custom tool call output in the OpenAI platform. + The keys being held while clicking. - - `agent: Agent{ agent_name}` + - `class DoubleClick` - The agent that produced this item. + A double click action. - - `agent_name: String` + - `keys: Array[String]` - The canonical name of the agent that produced this item. + The keys being held while double-clicking. - - `caller_: Direct{ type} | Program{ 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`. - - `class Direct` + - `:double_click` - - `type: :direct` + - `x: Integer` - The caller type. Always `direct`. + The x-coordinate where the double click occurred. - - `:direct` + - `y_: Integer` - - `class Program` + The y-coordinate where the double click occurred. - - `caller_id: String` + - `class Drag` - The call ID of the program item that produced this tool call. + A drag action. - - `type: :program` + - `path: Array[Path{ 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 } + ] + ``` - - `class BetaResponseCustomToolCall` + - `x: Integer` - A call to a custom tool created by the model. + The x-coordinate. - - `call_id: String` + - `y_: Integer` - 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: Array[String]` - - `type: :custom_tool_call` + The keys being held while dragging the mouse. - The type of the custom tool call. Always `custom_tool_call`. + - `class Keypress` - - `:custom_tool_call` + A collection of keypresses the model would like to perform. - - `id: String` + - `keys: Array[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: Agent{ 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. + - `class Move` - - `caller_: Direct{ type} | Program{ caller_id, type}` + A mouse move action. - The execution context that produced this tool call. + - `type: :move` - - `class Direct` + Specifies the event type. For a move action, this property is always set to `move`. - - `type: :direct` + - `:move` - - `:direct` + - `x: Integer` - - `class Program` + The x-coordinate to move to. - - `caller_id: String` + - `y_: Integer` - The call ID of the program item that produced this tool call. + The y-coordinate to move to. - - `type: :program` + - `keys: Array[String]` - - `:program` + The keys being held while moving the mouse. - - `namespace: String` + - `class Screenshot` - The namespace of the custom tool being called. + A screenshot action. - - `class CompactionTrigger` + - `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`. + - `class Scroll` - - `:compaction_trigger` + A scroll action. - - `agent: Agent{ agent_name}` + - `scroll_x: Integer` - The agent that produced this item. + The horizontal scroll distance. - - `agent_name: String` + - `scroll_y: Integer` - The canonical name of the agent that produced this item. + The vertical scroll distance. - - `class ItemReference` + - `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: Integer` - - `agent: Agent{ agent_name}` + The x-coordinate where the scroll occurred. - The agent that produced this item. + - `y_: Integer` - - `agent_name: String` + The y-coordinate where the scroll occurred. - The canonical name of the agent that produced this item. + - `keys: Array[String]` - - `type: :item_reference` + The keys being held while scrolling. - The type of item to reference. Always `item_reference`. + - `class Type` - - `:item_reference` + An action to type in text. - - `class Program` + - `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` + - `class Wait` - 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: BetaComputerActionList` - - `:program` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `agent: Agent{ agent_name}` + - `class Click` - The agent that produced this item. + A click action. - - `agent_name: String` + - `class DoubleClick` - The canonical name of the agent that produced this item. + A double click action. - - `class ProgramOutput` + - `class Drag` - - `id: String` + A drag action. - The unique ID of this program output item. + - `class Keypress` - - `call_id: String` + A collection of keypresses the model would like to perform. - The call ID of the program item. + - `class Move` - - `result: String` + A mouse move action. - The result produced by the program item. + - `class Screenshot` - - `status: :completed | :incomplete` + A screenshot action. - The terminal status of the program output. + - `class Scroll` - - `:completed` + A scroll action. - - `:incomplete` + - `class Type` - - `type: :program_output` + An action to type in text. - The item type. Always `program_output`. + - `class Wait` - - `:program_output` + A wait action. - `agent: Agent{ agent_name}` @@ -70006,451 +80787,452 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `metadata: Hash[Symbol, String]` + - `class ComputerCallOutput` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The output of a computer tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `call_id: String` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + The ID of the computer tool call that produced the 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + A computer screenshot image used with the computer use 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `type: :computer_screenshot` - - `:"gpt-5.6-sol"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:"gpt-5.6-terra"` + - `:computer_screenshot` - - `:"gpt-5.6-luna"` + - `file_id: String` - - `:"gpt-5.4"` + The identifier of an uploaded file that contains the screenshot. - - `:"gpt-5.4-mini"` + - `image_url: String` - - `:"gpt-5.4-nano"` + The URL of the screenshot image. - - `:"gpt-5.4-mini-2026-03-17"` + - `type: :computer_call_output` - - `:"gpt-5.4-nano-2026-03-17"` + The type of the computer tool call output. Always `computer_call_output`. - - `:"gpt-5.3-chat-latest"` + - `:computer_call_output` - - `:"gpt-5.2"` + - `id: String` - - `:"gpt-5.2-2025-12-11"` + The ID of the computer tool call output. - - `:"gpt-5.2-chat-latest"` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:"gpt-5.2-pro"` + The safety checks reported by the API that have been acknowledged by the developer. - - `:"gpt-5.2-pro-2025-12-11"` + - `id: String` - - `:"gpt-5.1"` + The ID of the pending safety check. - - `:"gpt-5.1-2025-11-13"` + - `code: String` - - `:"gpt-5.1-codex"` + The type of the pending safety check. - - `:"gpt-5.1-mini"` + - `message: String` - - `:"gpt-5.1-chat-latest"` + Details about the pending safety check. - - `:"gpt-5"` + - `agent: Agent{ agent_name}` - - `:"gpt-5-mini"` + The agent that produced this item. - - `:"gpt-5-nano"` + - `agent_name: String` - - `:"gpt-5-2025-08-07"` + The canonical name of the agent that produced this item. - - `:"gpt-5-mini-2025-08-07"` + - `status: :in_progress | :completed | :incomplete` - - `:"gpt-5-nano-2025-08-07"` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `:"gpt-5-chat-latest"` + - `:in_progress` - - `:"gpt-4.1"` + - `:completed` - - `:"gpt-4.1-mini"` + - `:incomplete` - - `:"gpt-4.1-nano"` + - `class BetaResponseFunctionWebSearch` - - `:"gpt-4.1-2025-04-14"` + 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-4.1-mini-2025-04-14"` + - `id: String` - - `:"gpt-4.1-nano-2025-04-14"` + The unique ID of the web search tool call. - - `:"o4-mini"` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `:"o4-mini-2025-04-16"` + 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). - - `:o3` + - `class Search` - - `:"o3-2025-04-16"` + Action type "search" - Performs a web search query. - - `:"o3-mini"` + - `type: :search` - - `:"o3-mini-2025-01-31"` + The action type. - - `:o1` + - `:search` - - `:"o1-2024-12-17"` + - `queries: Array[String]` - - `:"o1-preview"` + The search queries. - - `:"o1-preview-2024-09-12"` + - `query: String` - - `:"o1-mini"` + The search query. - - `:"o1-mini-2024-09-12"` + - `sources: Array[Source{ type, url}]` - - `:"gpt-4o"` + The sources used in the search. - - `:"gpt-4o-2024-11-20"` + - `type: :url` - - `:"gpt-4o-2024-08-06"` + The type of source. Always `url`. - - `:"gpt-4o-2024-05-13"` + - `:url` - - `:"gpt-4o-audio-preview"` + - `url: String` - - `:"gpt-4o-audio-preview-2024-10-01"` + The URL of the source. - - `:"gpt-4o-audio-preview-2024-12-17"` + - `class OpenPage` - - `:"gpt-4o-audio-preview-2025-06-03"` + Action type "open_page" - Opens a specific URL from search results. - - `:"gpt-4o-mini-audio-preview"` + - `type: :open_page` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + The action type. - - `:"gpt-4o-search-preview"` + - `:open_page` - - `:"gpt-4o-mini-search-preview"` + - `url: String` - - `:"gpt-4o-search-preview-2025-03-11"` + The URL opened by the model. - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `class FindInPage` - - `:"chatgpt-4o-latest"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `:"codex-mini-latest"` + - `pattern: String` - - `:"gpt-4o-mini"` + The pattern or text to search for within the page. - - `:"gpt-4o-mini-2024-07-18"` + - `type: :find_in_page` - - `:"gpt-4-turbo"` + The action type. - - `:"gpt-4-turbo-2024-04-09"` + - `:find_in_page` - - `:"gpt-4-0125-preview"` + - `url: String` - - `:"gpt-4-turbo-preview"` + The URL of the page searched for the pattern. - - `:"gpt-4-1106-preview"` + - `status: :in_progress | :searching | :completed | :failed` - - `:"gpt-4-vision-preview"` + The status of the web search tool call. - - `:"gpt-4"` + - `:in_progress` - - `:"gpt-4-0314"` + - `:searching` - - `:"gpt-4-0613"` + - `:completed` - - `:"gpt-4-32k"` + - `:failed` - - `:"gpt-4-32k-0314"` + - `type: :web_search_call` - - `:"gpt-4-32k-0613"` + The type of the web search tool call. Always `web_search_call`. - - `:"gpt-3.5-turbo"` + - `:web_search_call` - - `:"gpt-3.5-turbo-16k"` + - `agent: Agent{ agent_name}` - - `:"gpt-3.5-turbo-0301"` + The agent that produced this item. - - `:"gpt-3.5-turbo-0613"` + - `agent_name: String` - - `:"gpt-3.5-turbo-1106"` + The canonical name of the agent that produced this item. - - `:"gpt-3.5-turbo-0125"` + - `class BetaResponseFunctionToolCall` - - `:"gpt-3.5-turbo-16k-0613"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:"o1-pro"` + - `arguments: String` - - `:"o1-pro-2025-03-19"` + A JSON string of the arguments to pass to the function. - - `:"o3-pro"` + - `call_id: String` - - `:"o3-pro-2025-06-10"` + The unique ID of the function tool call generated by the model. - - `:"o3-deep-research"` + - `name: String` - - `:"o3-deep-research-2025-06-26"` + The name of the function to run. - - `:"o4-mini-deep-research"` + - `type: :function_call` - - `:"o4-mini-deep-research-2025-06-26"` + The type of the function tool call. Always `function_call`. - - `:"computer-use-preview"` + - `:function_call` - - `:"computer-use-preview-2025-03-11"` + - `id: String` - - `:"gpt-5-codex"` + The unique ID of the function tool call. - - `:"gpt-5-pro"` + - `agent: Agent{ agent_name}` - - `:"gpt-5-pro-2025-10-06"` + The agent that produced this item. - - `:"gpt-5.1-codex-max"` + - `agent_name: String` - - `String = String` + The canonical name of the agent that produced this item. - - `object: :response` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The object type of this resource - always set to `response`. + The execution context that produced this tool call. - - `:response` + - `class Direct` - - `output: Array[BetaResponseOutputItem]` + - `type: :direct` - An array of content items generated by the model. + - `:direct` - - 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. + - `class Program` - - `class BetaResponseOutputMessage` + - `caller_id: String` - An output message from the model. + The call ID of the program item that produced this tool call. - - `class BetaResponseFileSearchToolCall` + - `type: :program` - 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. + - `:program` - - `class BetaResponseFunctionToolCall` + - `namespace: String` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The namespace of the function to run. - - `class BetaResponseFunctionToolCallOutputItem` + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The unique ID of the function call tool output. + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class FunctionCallOutput` + + The output of a function tool call. - `call_id: String` The unique ID of the function tool call generated by the model. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `output: String | BetaResponseFunctionCallOutputItemList` - 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. - `String = String` - A string of the output of the function call. + A JSON string of the output of the function tool call. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - Text, image, or file output of the function call. + An array of content outputs (text, image, file) for the function tool call. - - `class BetaResponseInputText` + - `class BetaResponseInputTextContent` A text input to the model. - - `class BetaResponseInputImage` + - `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. - - `class BetaResponseInputFile` + - `type: :input_text` - A file input to the model. + The type of the input item. Always `input_text`. - - `status: :in_progress | :completed | :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: PromptCacheBreakpoint{ 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`. + - `class BetaResponseInputImageContent` - - `:function_call_output` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `agent: Agent{ 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: :low | :high | :auto | :original` - - `caller_: Direct{ type} | Program{ 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` - - `class Direct` + - `:high` - - `type: :direct` + - `:auto` - The caller type. Always `direct`. + - `:original` - - `:direct` + - `file_id: String` - - `class Program` + The ID of the file to be sent to the model. - - `caller_id: String` + - `image_url: 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: PromptCacheBreakpoint{ 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: String` + The breakpoint mode. Always `explicit`. - The identifier of the actor that created the item. + - `:explicit` - - `class AgentMessage` + - `class BetaResponseInputFileContent` - - `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[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `detail: :auto | :low | :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`. - - `class BetaResponseInputText` + - `:auto` - A text input to the model. + - `:low` - - `class BetaResponseOutputText` + - `:high` - A text output from the model. + - `file_data: String` - - `class Text` + The base64-encoded data of the file to be sent to the model. - A text content. + - `file_id: String` - - `text: String` + The ID of the file to be sent to the model. - - `type: :text` + - `file_url: String` - - `:text` + The URL of the file to be sent to the model. - - `class SummaryText` + - `filename: String` - A summary text from the model. + The name of the file to be sent to the model. - - `text: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` - - `class ReasoningText` + - `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: 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: Agent{ agent_name}` - - `:reasoning_text` + The agent that produced this item. - - `class BetaResponseOutputRefusal` + - `agent_name: String` - A refusal from the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImage` + - `caller_: Direct{ type} | Program{ 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. - - `class ComputerScreenshot` + - `class Direct` - A screenshot of a computer. + - `type: :direct` - - `detail: :low | :high | :auto | :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` + - `class Program` - - `: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: :in_progress | :completed | :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: PromptCacheBreakpoint{ mode}` + - `class AgentMessage` - Marks the exact end of a reusable 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[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `class BetaResponseInputFile` + Plaintext, image, or encrypted content sent between agents. - A file input to the model. + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `class EncryptedContent` @@ -70472,10 +81254,14 @@ puts(beta_compacted_response) - `type: :agent_message` - The type of the item. Always `agent_message`. + The item type. Always `agent_message`. - `:agent_message` + - `id: String` + + The unique ID of this agent message item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -70486,13 +81272,9 @@ puts(beta_compacted_response) - `class MultiAgentCall` - - `id: String` - - The unique ID of the multi-agent call item. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The multi-agent action to execute. + The multi-agent action that was executed. - `:spawn_agent` @@ -70508,7 +81290,7 @@ puts(beta_compacted_response) - `arguments: String` - The JSON string of arguments generated for the action. + The action arguments as a JSON string. - `call_id: String` @@ -70516,10 +81298,14 @@ puts(beta_compacted_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: String` + + The unique ID of this multi-agent call. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -70530,10 +81316,6 @@ puts(beta_compacted_response) - `class MultiAgentCallOutput` - - `id: String` - - The unique ID of the multi-agent call output item. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` The multi-agent action that produced this result. @@ -70554,30 +81336,106 @@ puts(beta_compacted_response) The unique ID of the multi-agent call. - - `output: Array[BetaResponseOutputText]` + - `output: Array[Output{ text, type, annotations}]` Text output returned by the multi-agent action. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ 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`. + The content type. Always `output_text`. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:output_text` + + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + Citations associated with the text content. + + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The citation type. Always `file_citation`. + + - `:file_citation` + + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + + - `end_index: Integer` + + The index of the last character of the citation in the message. + + - `start_index: Integer` + + 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. + + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + - `container_id: String` + + The ID of the container. + + - `end_index: Integer` + + 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: Integer` + + 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 type of the multi-agent result. Always `multi_agent_call_output`. + The item type. Always `multi_agent_call_output`. - `:multi_agent_call_output` + - `id: String` + + The unique ID of this multi-agent call output. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -70586,2016 +81444,1997 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch` + - `class ToolSearchCall` - 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. + - `arguments: untyped` - - `class BetaResponseComputerToolCall` + The arguments supplied to the tool search call. - 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: :tool_search_call` - - `class BetaResponseComputerToolCallOutputItem` + The item type. Always `tool_search_call`. + + - `:tool_search_call` - `id: String` - The unique ID of the computer call tool output. + The unique ID of this tool search call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. - `call_id: String` - The ID of the computer tool call that produced the output. + The unique ID of the tool search call generated by the model. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `execution: :server | :client` - A computer screenshot image used with the computer use tool. + Whether tool search was executed by the server or by the client. - - `status: :completed | :incomplete | :failed | :in_progress` + - `:server` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search call. + + - `:in_progress` - `:completed` - `:incomplete` - - `:failed` + - `class BetaResponseToolSearchOutputItemParam` - - `:in_progress` + - `tools: Array[BetaTool]` - - `type: :computer_call_output` + The loaded tool definitions returned by the tool search output. - The type of the computer tool call output. Always `computer_call_output`. + - `class BetaFunctionTool` - - `:computer_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). - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `name: String` - The safety checks reported by the API that have been acknowledged by the - developer. + The name of the function to call. - - `id: String` + - `parameters: Hash[Symbol, untyped]` - The ID of the pending safety check. + A JSON schema object describing the parameters of the function. - - `code: String` + - `strict: bool` - The type of the pending safety check. + Whether strict parameter validation is enforced for this function tool. - - `message: String` + - `type: :function` - Details about the pending safety check. + The type of the function tool. Always `function`. - - `agent: Agent{ agent_name}` + - `:function` - The agent that produced this item. + - `allowed_callers: Array[:direct | :programmatic]` - - `agent_name: String` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `:direct` - - `created_by: String` + - `:programmatic` - The identifier of the actor that created the item. + - `defer_loading: bool` - - `class BetaResponseReasoningItem` + Whether this function is deferred and loaded via tool search. - 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). + - `description: String` - - `class Program` + A description of the function. Used by the model to determine whether or not to call the function. - - `id: String` + - `output_schema: Hash[Symbol, untyped]` - The unique ID of the program item. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `call_id: String` + - `class BetaFileSearchTool` - The stable call ID of the program 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). - - `code: String` + - `type: :file_search` - The JavaScript source executed by programmatic tool calling. + The type of the file search tool. Always `file_search`. - - `fingerprint: String` + - `:file_search` - Opaque program replay fingerprint that must be round-tripped. + - `vector_store_ids: Array[String]` - - `type: :program` + The IDs of the vector stores to search. - The type of the item. Always `program`. + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `:program` + A filter to apply. - - `agent: Agent{ agent_name}` + - `class ComparisonFilter` - 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. - - `class ProgramOutput` + - `type: :eq | :ne | :gt | 5 more` - - `id: String` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The unique ID of the program output 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 - - `call_id: String` + - `:eq` - The call ID of the program item. + - `:ne` - - `result: String` + - `:gt` - The result produced by the program item. + - `:gte` - - `status: :completed | :incomplete` + - `:lt` - The terminal status of the program output item. + - `:lte` - - `:completed` + - `:in` - - `:incomplete` + - `:nin` - - `type: :program_output` + - `value: String | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` - The type of the item. Always `program_output`. + - `Float = Float` - - `:program_output` + - `UnionMember2 = bool` - - `agent: Agent{ agent_name}` + - `UnionMember3 = Array[String | Float]` - The agent that produced this item. + - `String = String` - - `agent_name: String` + - `Float = Float` - The canonical name of the agent that produced this item. + - `class CompoundFilter` - - `class BetaResponseToolSearchCall` + Combine multiple filters using `and` or `or`. - - `id: String` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - The unique ID of the tool search call item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `arguments: untyped` + - `class ComparisonFilter` - Arguments used for the tool search call. + 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 tool search call generated by the model. + The key to compare against the value. - - `execution: :server | :client` + - `type: :eq | :ne | :gt | 5 more` - Whether tool search was executed by the server or by the client. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:server` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `:client` + - `:eq` - - `status: :in_progress | :completed | :incomplete` + - `:ne` - The status of the tool search call item that was recorded. + - `:gt` - - `:in_progress` + - `:gte` - - `:completed` + - `:lt` - - `:incomplete` + - `:lte` - - `type: :tool_search_call` + - `:in` - The type of the item. Always `tool_search_call`. + - `:nin` - - `:tool_search_call` + - `value: String | Float | bool | Array[String | Float]` - - `agent: Agent{ agent_name}` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that produced this item. + - `String = String` - - `agent_name: String` + - `Float = Float` - The canonical name of the agent that produced this item. + - `UnionMember2 = bool` - - `created_by: String` + - `UnionMember3 = Array[String | Float]` - The identifier of the actor that created the item. + - `String = String` - - `class BetaResponseToolSearchOutputItem` + - `Float = Float` - - `id: String` + - `UnionMember1 = untyped` - The unique ID of the tool search output item. + - `type: :and | :or` - - `call_id: String` + Type of operation: `and` or `or`. - The unique ID of the tool search call generated by the model. + - `:and` - - `execution: :server | :client` + - `:or` - Whether tool search was executed by the server or by the client. + - `max_num_results: Integer` - - `:server` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `:client` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - - `status: :in_progress | :completed | :incomplete` + Ranking options for search. - The status of the tool search output item that was recorded. + - `hybrid_search: HybridSearch{ 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: Float` - - `:incomplete` + The weight of the embedding in the reciprocal ranking fusion. - - `tools: Array[BetaTool]` + - `text_weight: Float` - The loaded tool definitions returned by tool search. + The weight of the text in the reciprocal ranking fusion. - - `class BetaFunctionTool` + - `ranker: :auto | :"default-2024-11-15"` - 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 ranker to use for the file search. - - `class BetaFileSearchTool` + - `:auto` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `:"default-2024-11-15"` - - `class BetaComputerTool` + - `score_threshold: Float` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `class BetaComputerUsePreviewTool` + - `class BetaComputerTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaWebSearchTool` + - `type: :computer` - 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 the computer tool. Always `computer`. - - `class Mcp` + - `:computer` - 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). + - `class BetaComputerUsePreviewTool` - - `class CodeInterpreter` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A tool that runs Python code to help generate a response to a prompt. + - `display_height: Integer` - - `class ProgrammaticToolCalling` + The height of the computer display. - - `class ImageGeneration` + - `display_width: Integer` - A tool that generates images using the GPT image models. + The width of the computer display. - - `class LocalShell` + - `environment: :windows | :mac | :linux | 2 more` - A tool that allows the model to execute shell commands in a local environment. + The type of computer environment to control. - - `class BetaFunctionShellTool` + - `:windows` - A tool that allows the model to execute shell commands. + - `:mac` - - `class BetaCustomTool` + - `:linux` - 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) + - `:ubuntu` - - `class BetaNamespaceTool` + - `:browser` - Groups function/custom tools under a shared namespace. + - `type: :computer_use_preview` - - `class BetaToolSearchTool` + The type of the computer use tool. Always `computer_use_preview`. - Hosted or BYOT tool search configuration for deferred tools. + - `:computer_use_preview` - - `class BetaWebSearchPreviewTool` + - `class BetaWebSearchTool` - 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). + 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). - - `class BetaApplyPatchTool` + - `type: :web_search | :web_search_2025_08_26` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: :tool_search_output` + - `:web_search` - The type of the item. Always `tool_search_output`. + - `:web_search_2025_08_26` - - `:tool_search_output` + - `filters: Filters{ allowed_domains}` - - `agent: Agent{ agent_name}` + Filters for the search. - The agent that produced this item. + - `allowed_domains: Array[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"]` - - `created_by: String` + - `search_context_size: :low | :medium | :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. - - `class AdditionalTools` + - `:low` - - `id: String` + - `:medium` - The unique ID of the additional tools item. + - `:high` - - `role: :unknown | :user | :assistant | 5 more` + - `user_location: UserLocation{ city, country, region, 2 more}` - The role that provided the additional tools. + The approximate location of the user. - - `:unknown` + - `city: String` - - `:user` + Free text input for the city of the user, e.g. `San Francisco`. - - `:assistant` + - `country: String` - - `:system` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `:critic` + - `region: String` - - `:discriminator` + Free text input for the region of the user, e.g. `California`. - - `:developer` + - `timezone: String` - - `:tool` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `tools: Array[BetaTool]` + - `type: :approximate` - The additional tool definitions made available at this item. + The type of location approximation. Always `approximate`. - - `class BetaFunctionTool` + - `:approximate` - 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). + - `class Mcp` - - `class BetaFileSearchTool` + 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 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` - - `class BetaComputerTool` + A label for this MCP server, used to identify it in tool calls. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :mcp` - - `class BetaComputerUsePreviewTool` + The type of the MCP tool. Always `mcp`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:mcp` - - `class BetaWebSearchTool` + - `allowed_callers: Array[:direct | :programmatic]` - 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 tool invocation context(s). - - `class Mcp` + - `:direct` - 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). + - `:programmatic` - - `class CodeInterpreter` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - A tool that runs Python code to help generate a response to a prompt. + List of allowed tool names or a filter object. - - `class ProgrammaticToolCalling` + - `McpAllowedTools = Array[String]` - - `class ImageGeneration` + A string array of allowed tool names - A tool that generates images using the GPT image models. + - `class McpToolFilter` - - `class LocalShell` + A filter object to specify which tools are allowed. - A tool that allows the model to execute shell commands in a local environment. + - `read_only: bool` - - `class BetaFunctionShellTool` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A tool that allows the model to execute shell commands. + - `tool_names: Array[String]` - - `class BetaCustomTool` + List of allowed tool names. - 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) + - `authorization: String` - - `class BetaNamespaceTool` + 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. - Groups function/custom tools under a shared namespace. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `class BetaToolSearchTool` + 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). - Hosted or BYOT tool search configuration for deferred tools. + Currently supported `connector_id` values are: - - `class BetaWebSearchPreviewTool` + - 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` - 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). + - `:connector_dropbox` - - `class BetaApplyPatchTool` + - `:connector_gmail` - Allows the assistant to create, delete, or update files using unified diffs. + - `:connector_googlecalendar` - - `type: :additional_tools` + - `:connector_googledrive` - The type of the item. Always `additional_tools`. + - `:connector_microsoftteams` - - `:additional_tools` + - `:connector_outlookcalendar` - - `agent: Agent{ agent_name}` + - `:connector_outlookemail` - The agent that produced this item. + - `:connector_sharepoint` - - `agent_name: String` + - `defer_loading: bool` - The canonical name of the agent that produced this item. + Whether this MCP tool is deferred and discovered via tool search. - - `class BetaResponseCompactionItem` + - `headers: Hash[Symbol, String]` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `id: String` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - The unique ID of the compaction item. + Specify which of the MCP server's tools require approval. - - `encrypted_content: String` + - `class McpToolApprovalFilter` - The encrypted content that was produced by compaction. + 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: :compaction` + - `always: Always{ read_only, tool_names}` - The type of the item. Always `compaction`. + A filter object to specify which tools are allowed. - - `:compaction` + - `read_only: bool` - - `agent: Agent{ 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: Array[String]` - - `agent_name: String` + List of allowed tool names. - The canonical name of the agent that produced this item. + - `never: Never{ read_only, tool_names}` - - `created_by: String` + A filter object to specify which tools are allowed. - The identifier of the actor that created the item. + - `read_only: bool` - - `class ImageGenerationCall` + Indicates whether or not a tool modifies data or is read-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 image generation request made by the model. + - `tool_names: Array[String]` - - `id: String` + List of allowed tool names. - The unique ID of the image generation call. + - `McpToolApprovalSetting = :always | :never` - - `result: 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 generated image encoded in base64. + - `:always` - - `status: :in_progress | :completed | :generating | :failed` + - `:never` - The status of the image generation call. + - `server_description: String` - - `:in_progress` + Optional description of the MCP server, used to provide more context. - - `:completed` + - `server_url: String` - - `:generating` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:failed` + - `tunnel_id: String` - - `type: :image_generation_call` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The type of the image generation call. Always `image_generation_call`. + - `class CodeInterpreter` - - `:image_generation_call` + A tool that runs Python code to help generate a response to a prompt. - - `agent: Agent{ agent_name}` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - The agent that produced this item. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `agent_name: String` + - `String = String` - The canonical name of the agent that produced this item. + The container ID. - - `class BetaResponseCodeInterpreterToolCall` + - `class CodeInterpreterToolAuto` - A tool call to run code. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `class LocalShellCall` + - `type: :auto` - A tool call to run a command on the local shell. + Always `auto`. - - `id: String` + - `:auto` - The unique ID of the local shell call. + - `file_ids: Array[String]` - - `action: Action{ command, env, type, 3 more}` + An optional list of uploaded files to make available to your code. - Execute a shell command on the server. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `command: Array[String]` + The memory limit for the code interpreter container. - The command to run. + - `:"1g"` - - `env: Hash[Symbol, String]` + - `:"4g"` - Environment variables to set for the command. + - `:"16g"` - - `type: :exec` + - `:"64g"` - The type of the local shell action. Always `exec`. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:exec` + Network access policy for the container. - - `timeout_ms: Integer` + - `class BetaContainerNetworkPolicyDisabled` - Optional timeout in milliseconds for the command. + - `type: :disabled` - - `user: String` + Disable outbound network access. Always `disabled`. - Optional user to run the command as. + - `:disabled` - - `working_directory: String` + - `class BetaContainerNetworkPolicyAllowlist` - Optional working directory to run the command in. + - `allowed_domains: Array[String]` - - `call_id: String` + A list of allowed domains when type is `allowlist`. - The unique ID of the local shell tool call generated by the model. + - `type: :allowlist` - - `status: :in_progress | :completed | :incomplete` + Allow outbound network access only to specified domains. Always `allowlist`. - The status of the local shell call. + - `:allowlist` - - `:in_progress` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `:completed` + Optional domain-scoped secrets for allowlisted domains. - - `:incomplete` + - `domain: String` - - `type: :local_shell_call` + The domain associated with the secret. - The type of the local shell call. Always `local_shell_call`. + - `name: String` - - `:local_shell_call` + The name of the secret to inject for the domain. - - `agent: Agent{ 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`. - - `class LocalShellCallOutput` + - `:code_interpreter` - The output of a local shell tool call. + - `allowed_callers: Array[:direct | :programmatic]` - - `id: String` + The tool invocation context(s). - The unique ID of the local shell tool call generated by the model. + - `:direct` - - `output: String` + - `:programmatic` - A JSON string of the output of the local shell tool call. + - `class ProgrammaticToolCalling` - - `type: :local_shell_call_output` + - `type: :programmatic_tool_calling` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the tool. Always `programmatic_tool_calling`. - - `:local_shell_call_output` + - `:programmatic_tool_calling` - - `agent: Agent{ agent_name}` + - `class ImageGeneration` - The agent that produced this item. + A tool that generates images using the GPT image models. - - `agent_name: String` + - `type: :image_generation` - The canonical name of the agent that produced this item. + The type of the image generation tool. Always `image_generation`. - - `status: :in_progress | :completed | :incomplete` + - `:image_generation` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `action: :generate | :edit | :auto` - - `:in_progress` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `:completed` + - `:generate` - - `:incomplete` + - `:edit` - - `class BetaResponseFunctionShellToolCall` + - `:auto` - A tool call that executes one or more shell commands in a managed environment. + - `background: :transparent | :opaque | :auto` - - `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 ID of the shell tool call. Populated when this item is 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. - - `action: Action{ commands, max_output_length, timeout_ms}` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The shell commands and limits that describe how to run the tool call. + - `:transparent` - - `commands: Array[String]` + - `:opaque` - - `max_output_length: Integer` + - `:auto` - Optional maximum number of characters to return from each command. + - `input_fidelity: :high | :low` - - `timeout_ms: Integer` + 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`. - Optional timeout in milliseconds for the commands. + - `:high` - - `call_id: String` + - `:low` - The unique ID of the shell tool call generated by the model. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Represents the use of a local environment to perform shell actions. + - `file_id: String` - - `class BetaResponseLocalEnvironment` + File ID for the mask image. - Represents the use of a local environment to perform shell actions. + - `image_url: String` - - `type: :local` + Base64-encoded mask image. - The environment type. Always `local`. + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:local` + The image generation model to use. Default: `gpt-image-1`. - - `class BetaResponseContainerReference` + - `String = String` - Represents a container created with /v1/containers. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `container_id: String` + The image generation model to use. Default: `gpt-image-1`. - - `type: :container_reference` + - `:"gpt-image-1"` - The environment type. Always `container_reference`. + - `:"gpt-image-1-mini"` - - `:container_reference` + - `:"gpt-image-2"` - - `status: :in_progress | :completed | :incomplete` + - `:"gpt-image-2-2026-04-21"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `:"gpt-image-1.5"` - - `:in_progress` + - `:"chatgpt-image-latest"` - - `:completed` + - `moderation: :auto | :low` - - `:incomplete` + Moderation level for the generated image. Default: `auto`. - - `type: :shell_call` + - `:auto` - The type of the item. Always `shell_call`. + - `:low` - - `:shell_call` + - `output_compression: Integer` - - `agent: Agent{ agent_name}` + Compression level for the output image. Default: 100. - The agent that produced this item. + - `output_format: :png | :webp | :jpeg` - - `agent_name: String` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The canonical name of the agent that produced this item. + - `:png` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:webp` - The execution context that produced this tool call. + - `:jpeg` - - `class Direct` + - `partial_images: Integer` - - `type: :direct` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `:direct` + - `quality: :low | :medium | :high | :auto` - - `class Program` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller_id: String` + - `:low` - The call ID of the program item that produced this tool call. + - `:medium` - - `type: :program` + - `:high` - - `:program` + - `:auto` - - `created_by: String` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - The ID of the entity that created 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`. - - `class BetaResponseFunctionShellToolCallOutput` + - `String = String` - The output of a shell tool call that was emitted. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 shell call output. Populated when this item is returned via API. + - `:"1024x1024"` - - `call_id: String` + - `:"1024x1536"` - The unique ID of the shell tool call generated by the model. + - `:"1536x1024"` - - `max_output_length: Integer` + - `:auto` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class LocalShell` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + A tool that allows the model to execute shell commands in a local environment. - An array of shell call output contents + - `type: :local_shell` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + The type of the local shell tool. Always `local_shell`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `:local_shell` - - `class Timeout` + - `class BetaFunctionShellTool` - Indicates that the shell call exceeded its configured time limit. + A tool that allows the model to execute shell commands. - - `type: :timeout` + - `type: :shell` - The outcome type. Always `timeout`. + The type of the shell tool. Always `shell`. - - `:timeout` + - `:shell` - - `class Exit` + - `allowed_callers: Array[:direct | :programmatic]` - Indicates that the shell commands finished and returned an exit code. + The tool invocation context(s). - - `exit_code: Integer` + - `:direct` - Exit code from the shell process. + - `:programmatic` - - `type: :exit` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - The outcome type. Always `exit`. + - `class BetaContainerAuto` - - `:exit` + - `type: :container_auto` - - `stderr: String` + Automatically creates a container for this request - The standard error output that was captured. + - `:container_auto` - - `stdout: String` + - `file_ids: Array[String]` - The standard output that was captured. + An optional list of uploaded files to make available to your code. - - `created_by: String` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The identifier of the actor that created the item. + The memory limit for the container. - - `status: :in_progress | :completed | :incomplete` + - `:"1g"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `:"4g"` - - `:in_progress` + - `:"16g"` - - `:completed` + - `:"64g"` - - `:incomplete` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `type: :shell_call_output` + Network access policy for the container. - The type of the shell call output. Always `shell_call_output`. + - `class BetaContainerNetworkPolicyDisabled` - - `:shell_call_output` + - `class BetaContainerNetworkPolicyAllowlist` - - `agent: Agent{ agent_name}` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - The agent that produced this item. + An optional list of skills referenced by id or inline data. - - `agent_name: String` + - `class BetaSkillReference` - The canonical name of the agent that produced this item. + - `skill_id: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The ID of the referenced skill. - The execution context that produced this tool call. + - `type: :skill_reference` - - `class Direct` + References a skill created with the /v1/skills endpoint. - - `type: :direct` + - `:skill_reference` - - `:direct` + - `version: String` - - `class Program` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `caller_id: String` + - `class BetaInlineSkill` - The call ID of the program item that produced this tool call. + - `description: String` - - `type: :program` + The description of the skill. - - `:program` + - `name: String` - - `created_by: String` + The name of the skill. - The identifier of the actor that created the item. + - `source: BetaInlineSkillSource` - - `class BetaResponseApplyPatchToolCall` + Inline skill payload - A tool call that applies file diffs by creating, deleting, or updating files. + - `data: String` - - `id: String` + Base64-encoded skill zip bundle. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `media_type: :"application/zip"` - - `call_id: String` + The media type of the inline skill payload. Must be `application/zip`. - The unique ID of the apply patch tool call generated by the model. + - `:"application/zip"` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `type: :base64` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the inline skill source. Must be `base64`. - - `class CreateFile` + - `:base64` - Instruction describing how to create a file via the apply_patch tool. + - `type: :inline` - - `diff: String` + Defines an inline skill for this request. - Diff to apply. + - `:inline` - - `path: String` + - `class BetaLocalEnvironment` - Path of the file to create. + - `type: :local` - - `type: :create_file` + Use a local computer environment. - Create a new file with the provided diff. + - `:local` - - `:create_file` + - `skills: Array[BetaLocalSkill]` - - `class DeleteFile` + An optional list of skills. - Instruction describing how to delete a file via the apply_patch tool. + - `description: String` - - `path: String` + The description of the skill. - Path of the file to delete. + - `name: String` - - `type: :delete_file` + The name of the skill. - Delete the specified file. + - `path: String` - - `:delete_file` + The path to the directory containing the skill. - - `class UpdateFile` + - `class BetaContainerReference` - Instruction describing how to update a file via the apply_patch tool. + - `container_id: String` - - `diff: String` + The ID of the referenced container. - Diff to apply. + - `type: :container_reference` - - `path: String` + References a container created with the /v1/containers endpoint - Path of the file to update. + - `:container_reference` - - `type: :update_file` + - `class BetaCustomTool` - Update an existing file with the provided diff. + 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) - - `:update_file` + - `name: String` - - `status: :in_progress | :completed` + The name of the custom tool, used to identify it in tool calls. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `type: :custom` - - `:in_progress` + The type of the custom tool. Always `custom`. - - `:completed` + - `:custom` - - `type: :apply_patch_call` + - `allowed_callers: Array[:direct | :programmatic]` - The type of the item. Always `apply_patch_call`. + The tool invocation context(s). - - `:apply_patch_call` + - `:direct` - - `agent: Agent{ agent_name}` + - `:programmatic` - The agent that produced this item. + - `defer_loading: bool` - - `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: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Optional description of the custom tool, used to provide more context. - The execution context that produced this tool call. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `class Direct` + The input format for the custom tool. Default is unconstrained text. - - `type: :direct` + - `class Text` - - `:direct` + Unconstrained free-form text. - - `class Program` + - `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` + - `class Grammar` - - `:program` + A grammar defined by the user. - - `created_by: String` + - `definition: String` - The ID of the entity that created this tool call. + The grammar definition. - - `class BetaResponseApplyPatchToolCallOutput` + - `syntax: :lark | :regex` - The output emitted by an apply patch tool call. + The syntax of the grammar definition. One of `lark` or `regex`. - - `id: String` + - `:lark` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:regex` - - `call_id: String` + - `type: :grammar` - The unique ID of the apply patch tool call generated by the model. + Grammar format. Always `grammar`. - - `status: :completed | :failed` + - `:grammar` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `class BetaNamespaceTool` - - `:completed` + Groups function/custom tools under a shared namespace. - - `:failed` + - `description: String` - - `type: :apply_patch_call_output` + A description of the namespace shown to the model. - The type of the item. Always `apply_patch_call_output`. + - `name: String` - - `:apply_patch_call_output` + The namespace name used in tool calls (for example, `crm`). - - `agent: Agent{ agent_name}` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - The agent that produced this item. + The function/custom tools available inside this namespace. - - `agent_name: String` + - `class Function` - The canonical name of the agent that produced this item. + - `name: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `type: :function` - The execution context that produced this tool call. + - `:function` - - `class Direct` + - `allowed_callers: Array[:direct | :programmatic]` - - `type: :direct` + The tool invocation context(s). - `:direct` - - `class Program` + - `:programmatic` - - `caller_id: String` + - `defer_loading: bool` - The call ID of the program item that produced this tool call. + Whether this function should be deferred and discovered via tool search. - - `type: :program` + - `description: String` - - `:program` + - `output_schema: Hash[Symbol, untyped]` - - `created_by: 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 entity that created this tool call output. + - `parameters: untyped` - - `output: String` + - `strict: bool` - Optional textual output returned by the apply patch 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. - - `class McpCall` + - `class BetaCustomTool` - 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` + - `type: :namespace` - The unique ID of the tool call. + The type of the tool. Always `namespace`. - - `arguments: String` + - `:namespace` - A JSON string of the arguments passed to the tool. + - `class BetaToolSearchTool` - - `name: String` + Hosted or BYOT tool search configuration for deferred tools. - The name of the tool that was run. + - `type: :tool_search` - - `server_label: String` + The type of the tool. Always `tool_search`. - The label of the MCP server running the tool. + - `:tool_search` - - `type: :mcp_call` + - `description: String` - The type of the item. Always `mcp_call`. + Description shown to the model for a client-executed tool search tool. - - `:mcp_call` + - `execution: :server | :client` - - `agent: Agent{ 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: untyped` - - `approval_request_id: String` + Parameter schema for a client-executed tool search tool. - 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. + - `class BetaWebSearchPreviewTool` - - `error: 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 error from the tool call, if any. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `output: String` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The output from the tool call. + - `:web_search_preview` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `:web_search_preview_2025_03_11` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `search_content_types: Array[:text | :image]` - - `:in_progress` + - `:text` - - `:completed` + - `:image` - - `:incomplete` + - `search_context_size: :low | :medium | :high` - - `:calling` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `:failed` + - `:low` - - `class McpListTools` + - `:medium` - A list of tools available on an MCP server. + - `:high` - - `id: String` + - `user_location: UserLocation{ type, city, country, 2 more}` - The unique ID of the list. + The user's location. - - `server_label: String` + - `type: :approximate` - The label of the MCP server. + The type of location approximation. Always `approximate`. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `:approximate` - The tools available on the server. + - `city: String` - - `input_schema: untyped` + Free text input for the city of the user, e.g. `San Francisco`. - The JSON schema describing the tool's input. + - `country: 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 tool. + - `region: String` - - `annotations: untyped` + Free text input for the region of the user, e.g. `California`. - Additional annotations about the tool. + - `timezone: String` - - `description: String` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The description of the tool. + - `class BetaApplyPatchTool` - - `type: :mcp_list_tools` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the item. Always `mcp_list_tools`. + - `type: :apply_patch` - - `:mcp_list_tools` + The type of the tool. Always `apply_patch`. - - `agent: Agent{ agent_name}` + - `:apply_patch` - The agent that produced this item. + - `allowed_callers: Array[:direct | :programmatic]` - - `agent_name: String` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `:direct` - - `error: String` + - `:programmatic` - Error message if the server could not list tools. + - `type: :tool_search_output` - - `class McpApprovalRequest` + The item type. Always `tool_search_output`. - A request for human approval of a tool invocation. + - `:tool_search_output` - `id: String` - The unique ID of the approval request. + The unique ID of this tool search output. - - `arguments: String` + - `agent: Agent{ agent_name}` - A JSON string of arguments for the tool. + The agent that produced this item. - - `name: String` + - `agent_name: String` - The name of the tool to run. + The canonical name of the agent that produced this item. - - `server_label: String` + - `call_id: String` - The label of the MCP server making the request. + The unique ID of the tool search call generated by the model. - - `type: :mcp_approval_request` + - `execution: :server | :client` - The type of the item. Always `mcp_approval_request`. + Whether tool search was executed by the server or by the client. - - `:mcp_approval_request` + - `:server` - - `agent: Agent{ agent_name}` + - `:client` - The agent that produced this item. + - `status: :in_progress | :completed | :incomplete` - - `agent_name: String` + The status of the tool search output. + + - `:in_progress` + + - `:completed` - The canonical name of the agent that produced this item. + - `:incomplete` - - `class McpApprovalResponse` + - `class AdditionalTools` - A response to an MCP approval request. + - `role: :developer` - - `id: String` + The role that provided the additional tools. Only `developer` is supported. - The unique ID of the approval response + - `:developer` - - `approval_request_id: String` + - `tools: Array[BetaTool]` - The ID of the approval request being answered. + A list of additional tools made available at this item. - - `approve: bool` + - `class BetaFunctionTool` - Whether the request was approved. + 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: :mcp_approval_response` + - `class BetaFileSearchTool` - The type of the item. Always `mcp_approval_response`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `:mcp_approval_response` + - `class BetaComputerTool` - - `agent: Agent{ 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. + - `class BetaComputerUsePreviewTool` - - `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. + - `class BetaWebSearchTool` - - `reason: 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). - Optional reason for the decision. + - `class Mcp` - - `class BetaResponseCustomToolCall` + 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 call to a custom tool created by the model. + - `class CodeInterpreter` - - `class BetaResponseCustomToolCallOutputItem` + A tool that runs Python code to help generate a response to a prompt. - The output of a custom tool call from your code, being sent back to the model. + - `class ProgrammaticToolCalling` - - `id: String` + - `class ImageGeneration` - The unique ID of the custom tool call output item. + A tool that generates images using the GPT image models. - - `status: :in_progress | :completed | :incomplete` + - `class LocalShell` - 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` + - `class BetaFunctionShellTool` - - `:completed` + A tool that allows the model to execute shell commands. - - `:incomplete` + - `class BetaCustomTool` - - `created_by: 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 identifier of the actor that created the item. + - `class BetaNamespaceTool` - - `parallel_tool_calls: bool` + Groups function/custom tools under a shared namespace. - Whether to allow the model to run tool calls in parallel. + - `class BetaToolSearchTool` - - `temperature: Float` + Hosted or BYOT tool search configuration for deferred tools. - 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. + - `class BetaWebSearchPreviewTool` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 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). - 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. + - `class BetaApplyPatchTool` - - `BetaToolChoiceOptions = :none | :auto | :required` + Allows the assistant to create, delete, or update files using unified diffs. - Controls which (if any) tool is called by the model. + - `type: :additional_tools` - `none` means the model will not call any tool and instead generates a message. + The item type. Always `additional_tools`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `:additional_tools` - `required` means the model must call one or more tools. + - `id: String` - - `:none` + The unique ID of this additional tools item. - - `:auto` + - `agent: Agent{ agent_name}` - - `:required` + The agent that produced this item. - - `class BetaToolChoiceAllowed` + - `agent_name: String` - Constrains the tools available to the model to a pre-defined set. + The canonical name of the agent that produced this item. - - `mode: :auto | :required` + - `class BetaResponseReasoningItem` - Constrains the tools available to the model to a pre-defined set. + 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). - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `id: String` - `required` requires the model to call one or more of the allowed tools. + The unique identifier of the reasoning content. - - `:auto` + - `summary: Array[Summary{ text, type}]` - - `:required` + Reasoning summary content. - - `tools: Array[Hash[Symbol, untyped]]` + - `text: String` - A list of tool definitions that the model should be allowed to call. + A summary of the reasoning output from the model so far. - For the Responses API, the list of tool definitions might look like: + - `type: :summary_text` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of the object. Always `summary_text`. - - `type: :allowed_tools` + - `:summary_text` - Allowed tool configuration type. Always `allowed_tools`. + - `type: :reasoning` - - `:allowed_tools` + The type of the object. Always `reasoning`. - - `class BetaToolChoiceTypes` + - `:reasoning` - 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). + - `agent: Agent{ agent_name}` - - `type: :file_search | :web_search_preview | :computer | 5 more` + The agent that produced this item. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `agent_name: String` - Allowed values are: + The canonical name of the agent that produced this item. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `content: Array[Content{ text, type}]` - - `:file_search` + Reasoning text content. - - `:web_search_preview` + - `text: String` - - `:computer` + The reasoning text from the model. - - `:computer_use_preview` + - `type: :reasoning_text` - - `:computer_use` + The type of the reasoning text. Always `reasoning_text`. - - `:web_search_preview_2025_03_11` + - `:reasoning_text` - - `:image_generation` + - `encrypted_content: String` - - `:code_interpreter` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `class BetaToolChoiceFunction` + - `status: :in_progress | :completed | :incomplete` - Use this option to force the model to call a specific function. + 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 function to call. + - `:completed` - - `type: :function` + - `:incomplete` - For function calling, the type is always `function`. + - `class BetaResponseCompactionItemParam` - - `:function` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `class BetaToolChoiceMcp` + - `encrypted_content: String` - Use this option to force the model to call a specific tool on a remote MCP server. + The encrypted content of the compaction summary. - - `server_label: String` + - `type: :compaction` - The label of the MCP server to use. + The type of the item. Always `compaction`. - - `type: :mcp` + - `:compaction` - For MCP tools, the type is always `mcp`. + - `id: String` - - `:mcp` + The ID of the compaction item. - - `name: String` + - `agent: Agent{ agent_name}` - The name of the tool to call on the server. + The agent that produced this item. - - `class BetaToolChoiceCustom` + - `agent_name: String` - Use this option to force the model to call a specific custom tool. + The canonical name of the agent that produced this item. - - `name: String` + - `class ImageGenerationCall` - The name of the custom tool to call. + An image generation request made by the model. - - `type: :custom` + - `id: String` - For custom tool calling, the type is always `custom`. + The unique ID of the image generation call. - - `:custom` + - `result: String` - - `class BetaSpecificProgrammaticToolCallingParam` + The generated image encoded in base64. - - `type: :programmatic_tool_calling` + - `status: :in_progress | :completed | :generating | :failed` - The tool to call. Always `programmatic_tool_calling`. + The status of the image generation call. - - `:programmatic_tool_calling` + - `:in_progress` - - `class BetaToolChoiceApplyPatch` + - `:completed` - Forces the model to call the apply_patch tool when executing a tool call. + - `:generating` - - `type: :apply_patch` + - `:failed` - The tool to call. Always `apply_patch`. + - `type: :image_generation_call` - - `:apply_patch` + The type of the image generation call. Always `image_generation_call`. - - `class BetaToolChoiceShell` + - `:image_generation_call` - Forces the model to call the shell tool when a tool call is required. + - `agent: Agent{ agent_name}` - - `type: :shell` + The agent that produced this item. - The tool to call. Always `shell`. + - `agent_name: String` - - `:shell` + The canonical name of the agent that produced this item. - - `tools: Array[BetaTool]` + - `class BetaResponseCodeInterpreterToolCall` - 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 tool call to run code. - We support the following categories of tools: + - `id: 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 unique ID of the code interpreter tool call. - - `class BetaFunctionTool` + - `code: 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 code to run, or null if not available. - - `class BetaFileSearchTool` + - `container_id: String` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The ID of the container used to run the code. - - `class BetaComputerTool` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `class BetaComputerUsePreviewTool` + - `class Logs` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The logs output from the code interpreter. - - `class BetaWebSearchTool` + - `logs: 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 logs output from the code interpreter. - - `class Mcp` + - `type: :logs` - 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 type of the output. Always `logs`. - - `class CodeInterpreter` + - `:logs` - A tool that runs Python code to help generate a response to a prompt. + - `class Image` - - `class ProgrammaticToolCalling` + The image output from the code interpreter. - - `class ImageGeneration` + - `type: :image` - A tool that generates images using the GPT image models. + The type of the output. Always `image`. - - `class LocalShell` + - `:image` - A tool that allows the model to execute shell commands in a local environment. + - `url: String` - - `class BetaFunctionShellTool` + The URL of the image output from the code interpreter. - A tool that allows the model to execute shell commands. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `class BetaCustomTool` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `:in_progress` - - `class BetaNamespaceTool` + - `:completed` - Groups function/custom tools under a shared namespace. + - `:incomplete` - - `class BetaToolSearchTool` + - `:interpreting` - Hosted or BYOT tool search configuration for deferred tools. + - `:failed` - - `class BetaWebSearchPreviewTool` + - `type: :code_interpreter_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 code interpreter tool call. Always `code_interpreter_call`. - - `class BetaApplyPatchTool` + - `:code_interpreter_call` - Allows the assistant to create, delete, or update files using unified diffs. + - `agent: Agent{ agent_name}` - - `top_p: Float` + 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. - - `background: bool` + - `class LocalShellCall` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + A tool call to run a command on the local shell. - - `completed_at: Float` + - `id: String` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The unique ID of the local shell call. - - `conversation: Conversation{ id}` + - `action: Action{ command, env, type, 3 more}` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + Execute a shell command on the server. - - `id: String` + - `command: Array[String]` - The unique ID of the conversation that this response was associated with. + The command to run. - - `max_output_tokens: Integer` + - `env: Hash[Symbol, 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). + Environment variables to set for the command. - - `max_tool_calls: Integer` + - `type: :exec` - 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 local shell action. Always `exec`. - - `moderation: Moderation{ input, output}` + - `:exec` - Moderation results for the response input and output, if moderated completions were requested. + - `timeout_ms: Integer` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + Optional timeout in milliseconds for the command. - Moderation for the response input. + - `user: String` - - `class ModerationResult` + Optional user to run the command as. - A moderation result produced for the response input or output. + - `working_directory: String` - - `categories: Hash[Symbol, bool]` + Optional working directory to run the command in. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `call_id: String` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The unique ID of the local shell tool call generated by the model. - Which modalities of input are reflected by the score for each category. + - `status: :in_progress | :completed | :incomplete` - - `:text` + The status of the local shell call. - - `:image` + - `:in_progress` - - `category_scores: Hash[Symbol, Float]` + - `:completed` - A dictionary of moderation categories to scores. + - `:incomplete` - - `flagged: bool` + - `type: :local_shell_call` - A boolean indicating whether the content was flagged by any category. + The type of the local shell call. Always `local_shell_call`. - - `model: String` + - `:local_shell_call` - The moderation model that produced this result. + - `agent: Agent{ 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. - - `class Error` + - `class LocalShellCallOutput` - An error produced while attempting moderation for the response input or output. + The output of a local shell tool call. - - `code: String` + - `id: String` - The error code. + The unique ID of the local shell tool call generated by the model. - - `message: String` + - `output: String` - The error message. + A JSON string of the output of the local shell tool call. - - `type: :error` + - `type: :local_shell_call_output` - The object type, which was always `error` for moderation failures. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:error` + - `:local_shell_call_output` - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `agent: Agent{ agent_name}` - Moderation for the response output. + The agent that produced this item. - - `class ModerationResult` + - `agent_name: String` - A moderation result produced for the response input or output. + The canonical name of the agent that produced this item. - - `categories: Hash[Symbol, bool]` + - `status: :in_progress | :completed | :incomplete` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `:in_progress` - Which modalities of input are reflected by the score for each category. + - `:completed` - - `:text` + - `:incomplete` - - `:image` + - `class ShellCall` - - `category_scores: Hash[Symbol, Float]` + A tool representing a request to execute one or more shell commands. - A dictionary of moderation categories to scores. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `flagged: bool` + The shell commands and limits that describe how to run the tool call. - A boolean indicating whether the content was flagged by any category. + - `commands: Array[String]` - - `model: String` + Ordered shell commands for the execution environment to run. - The moderation model that produced this result. + - `max_output_length: Integer` - - `type: :moderation_result` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The object type, which was always `moderation_result` for successful moderation results. + - `timeout_ms: Integer` - - `:moderation_result` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `class Error` + - `call_id: String` - An error produced while attempting moderation for the response input or output. + The unique ID of the shell tool call generated by the model. - - `code: String` + - `type: :shell_call` - The error code. + The type of the item. Always `shell_call`. - - `message: String` + - `:shell_call` - The error message. + - `id: String` - - `type: :error` + The unique ID of the shell tool call. Populated when this item is returned via API. - The object type, which was always `error` for moderation failures. + - `agent: Agent{ agent_name}` - - `:error` + The agent that produced this item. - - `previous_response_id: String` + - `agent_name: 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 canonical name of the agent that produced this item. - - `prompt: BetaResponsePrompt` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The execution context that produced this tool call. - - `id: String` + - `class Direct` - The unique identifier of the prompt template to use. + - `type: :direct` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The caller type. Always `direct`. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `:direct` - - `String = String` + - `class Program` - - `class BetaResponseInputText` + - `caller_id: String` - A text input to the model. + The call ID of the program item that produced this tool call. - - `class BetaResponseInputImage` + - `type: :program` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The caller type. Always `program`. - - `class BetaResponseInputFile` + - `:program` - A file input to the model. + - `environment: BetaLocalEnvironment | BetaContainerReference` - - `version: String` + The environment to execute the shell commands in. - Optional version of the prompt template. + - `class BetaLocalEnvironment` - - `prompt_cache_key: String` + - `class BetaContainerReference` - 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). + - `status: :in_progress | :completed | :incomplete` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `:in_progress` - - `mode: :implicit | :explicit` + - `:completed` - Whether implicit prompt-cache breakpoints were enabled. + - `:incomplete` - - `:implicit` + - `class ShellCallOutput` - - `:explicit` + The streamed output items emitted by a shell tool call. - - `ttl: :"30m"` + - `call_id: String` - The minimum lifetime applied to each cache breakpoint. + The unique ID of the shell tool call generated by the model. - - `:"30m"` + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - - `prompt_cache_retention: :in_memory | :"24h"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](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 exit or timeout outcome associated with this shell call. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `class Timeout` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Indicates that the shell call exceeded its configured time limit. - - `:in_memory` + - `type: :timeout` - - `:"24h"` + The outcome type. Always `timeout`. - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `:timeout` - **gpt-5 and o-series models only** + - `class Exit` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Indicates that the shell commands finished and returned an exit code. - - `context: :auto | :current_turn | :all_turns` + - `exit_code: Integer` - 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 exit code returned by the shell process. - - `:auto` + - `type: :exit` - - `:current_turn` + The outcome type. Always `exit`. - - `:all_turns` + - `:exit` - - `effort: :none | :minimal | :low | 4 more` + - `stderr: 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. + Captured stderr output for the shell call. - - `:none` + - `stdout: String` - - `:minimal` + Captured stdout output for the shell call. - - `:low` + - `type: :shell_call_output` - - `:medium` + The type of the item. Always `shell_call_output`. - - `:high` + - `:shell_call_output` - - `:xhigh` + - `id: String` - - `:max` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `generate_summary: :auto | :concise | :detailed` + - `agent: Agent{ agent_name}` - **Deprecated:** use `summary` instead. + The agent that produced this item. - 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_name: String` - - `:auto` + The canonical name of the agent that produced this item. - - `:concise` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:detailed` + The execution context that produced this tool call. - - `mode: String | :standard | :pro` + - `class Direct` - Controls the reasoning execution mode for the request. + - `type: :direct` - When returned on a response, this is the effective execution mode. + The caller type. Always `direct`. - - `String = String` + - `:direct` - - `Mode = :standard | :pro` + - `class Program` - 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. - - `:standard` + - `type: :program` - - `:pro` + The caller type. Always `program`. - - `summary: :auto | :concise | :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`. + - `max_output_length: Integer` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `:auto` + - `status: :in_progress | :completed | :incomplete` - - `:concise` + The status of the shell call output. - - `:detailed` + - `:in_progress` - - `safety_identifier: String` + - `:completed` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `:incomplete` - - `service_tier: :auto | :default | :flex | 2 more` + - `class ApplyPatchCall` - Specifies the processing type used for serving the request. + A tool call representing a request to create, delete, or update files using diff patches. - - 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'. + - `call_id: 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 unique ID of the apply patch tool call generated by the model. - - `:auto` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `:default` + The specific create, delete, or update instruction for the apply_patch tool call. - - `:flex` + - `class CreateFile` - - `:scale` + Instruction for creating a new file via the apply_patch tool. - - `:priority` + - `diff: String` - - `status: BetaResponseStatus` + Unified diff content to apply when creating the file. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `path: String` - - `:completed` + Path of the file to create relative to the workspace root. - - `:failed` + - `type: :create_file` - - `:in_progress` + The operation type. Always `create_file`. - - `:cancelled` + - `:create_file` - - `:queued` + - `class DeleteFile` - - `:incomplete` + Instruction for deleting an existing file via the apply_patch tool. - - `text: BetaResponseTextConfig` + - `path: String` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Path of the file to delete relative to the workspace root. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `type: :delete_file` - - `format_: BetaResponseFormatTextConfig` + The operation type. Always `delete_file`. - An object specifying the format that the model must output. + - `:delete_file` - 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). + - `class UpdateFile` - The default format is `{ "type": "text" }` with no additional options. + Instruction for updating an existing file via the apply_patch tool. - **Not recommended for gpt-4o and newer models:** + - `diff: 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. + Unified diff content to apply to the existing file. - - `class Text` + - `path: String` - Default response format. Used to generate text responses. + Path of the file to update relative to the workspace root. - - `type: :text` + - `type: :update_file` - The type of response format being defined. Always `text`. + The operation type. Always `update_file`. - - `:text` + - `:update_file` - - `class BetaResponseFormatTextJSONSchemaConfig` + - `status: :in_progress | :completed` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `name: String` + - `:in_progress` - 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. + - `:completed` - - `schema: Hash[Symbol, untyped]` + - `type: :apply_patch_call` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the item. Always `apply_patch_call`. - - `type: :json_schema` + - `:apply_patch_call` - 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: String` + - `agent: Agent{ 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: bool` + - `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](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - - `class JSONObject` + - `caller_: Direct{ type} | Program{ 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. + The execution context that produced this tool call. - - `type: :json_object` + - `class Direct` - The type of response format being defined. Always `json_object`. + - `type: :direct` - - `:json_object` + The caller type. Always `direct`. - - `verbosity: :low | :medium | :high` + - `:direct` - 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`. + - `class Program` - - `:low` + - `caller_id: String` - - `:medium` + The call ID of the program item that produced this tool call. - - `:high` + - `type: :program` - - `top_logprobs: Integer` + The caller type. Always `program`. - 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` - - `truncation: :auto | :disabled` + - `class ApplyPatchCallOutput` - The truncation strategy to use for the model response. + The streamed output emitted by an apply patch 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. + - `call_id: String` - - `:auto` + The unique ID of the apply patch tool call generated by the model. - - `:disabled` + - `status: :completed | :failed` - - `usage: BetaResponseUsage` + The status of the apply patch tool call output. One of `completed` or `failed`. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `:completed` - - `input_tokens: Integer` + - `:failed` - The number of input tokens. + - `type: :apply_patch_call_output` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + The type of the item. Always `apply_patch_call_output`. - A detailed breakdown of the input tokens. + - `:apply_patch_call_output` - - `cache_write_tokens: Integer` + - `id: String` - The number of input tokens that were written to the cache. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `cached_tokens: Integer` + - `agent: Agent{ agent_name}` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The agent that produced this item. - - `output_tokens: Integer` + - `agent_name: String` - The number of output tokens. + The canonical name of the agent that produced this item. - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A detailed breakdown of the output tokens. + The execution context that produced this tool call. - - `reasoning_tokens: Integer` + - `class Direct` - The number of reasoning tokens. + - `type: :direct` - - `total_tokens: Integer` + The caller type. Always `direct`. - The total number of tokens used. + - `:direct` - - `user: String` + - `class Program` - 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_id: String` - - `sequence_number: Integer` + The call ID of the program item that produced this tool call. - The sequence number for this event. + - `type: :program` - - `type: :"response.created"` + The caller type. Always `program`. - The type of the event. Always `response.created`. + - `:program` - - `:"response.created"` + - `output: String` - - `agent: Agent{ agent_name}` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The agent that owns this multi-agent streaming event. + - `class McpListTools` - - `agent_name: String` + A list of tools available on an MCP server. - The canonical name of the agent that produced this item. + - `id: String` -### Beta Response Custom Tool Call + The unique ID of the list. -- `class BetaResponseCustomToolCall` + - `server_label: String` - A call to a custom tool created by the model. + The label of the MCP server. - - `call_id: String` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - An identifier used to map this custom tool call to a tool call output. + The tools available on the server. - - `input: String` + - `input_schema: untyped` - The input for the custom tool call generated by the model. + The JSON schema describing the tool's input. - `name: String` - The name of the custom tool being called. + The name of the tool. - - `type: :custom_tool_call` + - `annotations: untyped` - The type of the custom tool call. Always `custom_tool_call`. + Additional annotations about the tool. - - `:custom_tool_call` + - `description: String` - - `id: String` + The description of the tool. - The unique ID of the custom tool call in the OpenAI platform. + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` - `agent: Agent{ agent_name}` @@ -72605,116 +83444,128 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `error: String` - The execution context that produced this tool call. + Error message if the server could not list tools. - - `class Direct` + - `class McpApprovalRequest` - - `type: :direct` + A request for human approval of a tool invocation. - - `:direct` + - `id: String` - - `class Program` + The unique ID of the approval request. - - `caller_id: String` + - `arguments: String` - The call ID of the program item that produced this tool call. + A JSON string of arguments for the tool. - - `type: :program` + - `name: String` - - `:program` + The name of the tool to run. - - `namespace: String` + - `server_label: String` - The namespace of the custom tool being called. + The label of the MCP server making the request. -### Beta Response Custom Tool Call Input Delta Event + - `type: :mcp_approval_request` -- `class BetaResponseCustomToolCallInputDeltaEvent` + The type of the item. Always `mcp_approval_request`. - Event representing a delta (partial update) to the input of a custom tool call. + - `:mcp_approval_request` - - `delta: String` + - `agent: Agent{ agent_name}` - The incremental input data (delta) for the custom tool call. + The agent that produced this item. - - `item_id: String` + - `agent_name: String` - Unique identifier for the API item associated with this event. + The canonical name of the agent that produced this item. - - `output_index: Integer` + - `class McpApprovalResponse` - The index of the output this delta applies to. + A response to an MCP approval request. - - `sequence_number: Integer` + - `approval_request_id: String` - The sequence number of this event. + The ID of the approval request being answered. - - `type: :"response.custom_tool_call_input.delta"` + - `approve: bool` - The event type identifier. + Whether the request was approved. - - `:"response.custom_tool_call_input.delta"` + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response - `agent: Agent{ 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 Done Event + - `reason: String` -- `class BetaResponseCustomToolCallInputDoneEvent` + Optional reason for the decision. - Event indicating that input for a custom tool call is complete. + - `class McpCall` - - `input: String` + An invocation of a tool on an MCP server. - The complete input data for the custom tool call. + - `id: String` - - `item_id: String` + The unique ID of the tool call. - Unique identifier for the API item associated with this event. + - `arguments: String` - - `output_index: Integer` + A JSON string of the arguments passed to the tool. - The index of the output this event applies to. + - `name: String` - - `sequence_number: Integer` + The name of the tool that was run. - The sequence number of this event. + - `server_label: String` - - `type: :"response.custom_tool_call_input.done"` + The label of the MCP server running the tool. - The event type identifier. + - `type: :mcp_call` - - `:"response.custom_tool_call_input.done"` + The type of the item. Always `mcp_call`. + + - `:mcp_call` - `agent: Agent{ 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 Item + - `approval_request_id: String` -- `class BetaResponseCustomToolCallItem` + 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 call to a custom tool created by the model. + - `error: String` - - `id: String` + The error from the tool call, if any. - The unique ID of the custom tool call item. + - `output: String` - - `status: :in_progress | :completed | :incomplete` + The output from the tool call. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `:in_progress` @@ -72722,13 +83573,11 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` - - The identifier of the actor that created the item. + - `:calling` -### Beta Response Custom Tool Call Output + - `:failed` -- `class BetaResponseCustomToolCallOutput` + - `class BetaResponseCustomToolCallOutput` The output of a custom tool call from your code, being sent back to the model. @@ -72753,112 +83602,14 @@ puts(beta_compacted_response) 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: PromptCacheBreakpoint{ 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` - - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: :low | :high | :auto | :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: String` - - The ID of the file to be sent to the model. - - - `image_url: 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: PromptCacheBreakpoint{ 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` - - `class BetaResponseInputFile` A file input to the model. - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` - - The content of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: :custom_tool_call_output` The type of the custom tool call output. Always `custom_tool_call_output`. @@ -72901,216 +83652,209 @@ puts(beta_compacted_response) - `:program` -### Beta Response Custom Tool Call Output Item - -- `class BetaResponseCustomToolCallOutputItem` - - The output of a custom tool call from your code, being sent back to the model. + - `class BetaResponseCustomToolCall` - - `id: String` + A call to a custom tool created by the model. - The unique ID of the custom tool call output item. + - `call_id: String` - - `status: :in_progress | :completed | :incomplete` + An identifier used to map this custom tool call to a tool call output. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `input: String` - - `:in_progress` + The input for the custom tool call generated by the model. - - `:completed` + - `name: String` - - `:incomplete` + The name of the custom tool being called. - - `created_by: String` + - `type: :custom_tool_call` - The identifier of the actor that created the item. + The type of the custom tool call. Always `custom_tool_call`. -### Beta Response Error + - `:custom_tool_call` -- `class BetaResponseError` + - `id: String` - An error object returned when the model fails to generate a Response. + The unique ID of the custom tool call in the OpenAI platform. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `agent: Agent{ agent_name}` - The error code for the response. + The agent that produced this item. - - `:server_error` + - `agent_name: String` - - `:rate_limit_exceeded` + The canonical name of the agent that produced this item. - - `:invalid_prompt` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:bio_policy` + The execution context that produced this tool call. - - `:vector_store_timeout` + - `class Direct` - - `:invalid_image` + - `type: :direct` - - `:invalid_image_format` + - `:direct` - - `:invalid_base64_image` + - `class Program` - - `:invalid_image_url` + - `caller_id: String` - - `:image_too_large` + The call ID of the program item that produced this tool call. - - `:image_too_small` + - `type: :program` - - `:image_parse_error` + - `:program` - - `:image_content_policy_violation` + - `namespace: String` - - `:invalid_image_mode` + The namespace of the custom tool being called. - - `:image_file_too_large` + - `class CompactionTrigger` - - `:unsupported_image_media_type` + Compacts the current context. Must be the final input item. - - `:empty_image_file` + - `type: :compaction_trigger` - - `:failed_to_download_image` + The type of the item. Always `compaction_trigger`. - - `:image_file_not_found` + - `:compaction_trigger` - - `message: String` + - `agent: Agent{ agent_name}` - A human-readable description of the error. + The agent that produced this item. -### Beta Response Error Event + - `agent_name: String` -- `class BetaResponseErrorEvent` + The canonical name of the agent that produced this item. - Emitted when an error occurs. + - `class ItemReference` - - `code: String` + An internal identifier for an item to reference. - The error code. + - `id: String` - - `message: String` + The ID of the item to reference. - The error message. + - `agent: Agent{ agent_name}` - - `param: String` + The agent that produced this item. - The error parameter. + - `agent_name: String` - - `sequence_number: Integer` + The canonical name of the agent that produced this item. - The sequence number of this event. + - `type: :item_reference` - - `type: :error` + The type of item to reference. Always `item_reference`. - The type of the event. Always `error`. + - `:item_reference` - - `:error` + - `class Program` - - `agent: Agent{ agent_name}` + - `id: String` - The agent that owns this multi-agent streaming event. + The unique ID of this program item. - - `agent_name: String` + - `call_id: String` - The canonical name of the agent that produced this item. + The stable call ID of the program item. -### Beta Response Failed Event + - `code: String` -- `class BetaResponseFailedEvent` + The JavaScript source executed by programmatic tool calling. - An event that is emitted when a response fails. + - `fingerprint: String` - - `response: BetaResponse` + Opaque program replay fingerprint that must be round-tripped. - The response that failed. + - `type: :program` - - `id: String` + The item type. Always `program`. - Unique identifier for this Response. + - `:program` - - `created_at: Float` + - `agent: Agent{ agent_name}` - Unix timestamp (in seconds) of when this Response was created. + The agent that produced this item. - - `error: BetaResponseError` + - `agent_name: String` - An error object returned when the model fails to generate a Response. + The canonical name of the agent that produced this item. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `class ProgramOutput` - The error code for the response. + - `id: String` - - `:server_error` + The unique ID of this program output item. - - `:rate_limit_exceeded` + - `call_id: String` - - `:invalid_prompt` + The call ID of the program item. - - `:bio_policy` + - `result: String` - - `:vector_store_timeout` + The result produced by the program item. - - `:invalid_image` + - `status: :completed | :incomplete` - - `:invalid_image_format` + The terminal status of the program output. - - `:invalid_base64_image` + - `:completed` - - `:invalid_image_url` + - `:incomplete` - - `:image_too_large` + - `type: :program_output` - - `:image_too_small` + The item type. Always `program_output`. - - `:image_parse_error` + - `:program_output` - - `:image_content_policy_violation` + - `agent: Agent{ agent_name}` - - `:invalid_image_mode` + The agent that produced this item. - - `:image_file_too_large` + - `agent_name: String` - - `:unsupported_image_media_type` + The canonical name of the agent that produced this item. - - `:empty_image_file` + - `response_id: String` - - `:failed_to_download_image` + The ID of the active response that should receive the input. - - `:image_file_not_found` + - `type: :"response.inject"` - - `message: String` + The event discriminator. Always `response.inject`. - A human-readable description of the error. + - `:"response.inject"` - - `incomplete_details: IncompleteDetails{ reason}` +### Beta Response Inject Failed Event - Details about why the response is incomplete. +- `class BetaResponseInjectFailedEvent` - - `reason: :max_output_tokens | :content_filter` + 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 reason why the response is incomplete. + - `error: Error{ code, message}` - - `:max_output_tokens` + Information about why the input was not committed. - - `:content_filter` + - `code: :response_already_completed | :response_not_found` - - `instructions: String | Array[BetaResponseInputItem]` + A machine-readable error code. - A system (or developer) message inserted into the model's context. + - `:response_already_completed` - 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. + - `:response_not_found` - - `String = String` + - `message: String` - A text input to the model, equivalent to a text input with the - `developer` role. + A human-readable description of the error. - - `InputItemList = Array[BetaResponseInputItem]` + - `input: Array[BetaResponseInputItem]` - A list of one or many input items to the model, containing - different content types. + The raw input items that were not committed. - `class BetaEasyInputMessage` @@ -73257,7 +84001,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :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 @@ -73265,6 +84009,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -73504,7 +84250,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -73512,6 +84258,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -74684,7 +85432,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -74694,7 +85442,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -74741,7 +85493,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -74751,7 +85503,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -76901,286 +87657,540 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `metadata: Hash[Symbol, String]` + - `response_id: String` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The ID of the response that rejected the input. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `sequence_number: Integer` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + The sequence number for this 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `type: :"response.inject.failed"` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + The event discriminator. Always `response.inject.failed`. - 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. + - `:"response.inject.failed"` - - `:"gpt-5.6-sol"` + - `stream_id: String` - - `:"gpt-5.6-terra"` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `:"gpt-5.6-luna"` +### Beta Response Input - - `:"gpt-5.4"` +- `BetaResponseInput = Array[BetaResponseInputItem]` - - `:"gpt-5.4-mini"` + A list of one or many input items to the model, containing + different content types. - - `:"gpt-5.4-nano"` + - `class BetaEasyInputMessage` - - `:"gpt-5.4-mini-2026-03-17"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `:"gpt-5.4-nano-2026-03-17"` + - `content: String | BetaResponseInputMessageContentList` - - `:"gpt-5.3-chat-latest"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `:"gpt-5.2"` + - `String = String` - - `:"gpt-5.2-2025-12-11"` + A text input to the model. - - `:"gpt-5.2-chat-latest"` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `:"gpt-5.2-pro"` + A list of one or many input items to the model, containing different content + types. - - `:"gpt-5.2-pro-2025-12-11"` + - `class BetaResponseInputText` - - `:"gpt-5.1"` + A text input to the model. - - `:"gpt-5.1-2025-11-13"` + - `text: String` - - `:"gpt-5.1-codex"` + The text input to the model. - - `:"gpt-5.1-mini"` + - `type: :input_text` - - `:"gpt-5.1-chat-latest"` + The type of the input item. Always `input_text`. - - `:"gpt-5"` + - `:input_text` - - `:"gpt-5-mini"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:"gpt-5-nano"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:"gpt-5-2025-08-07"` + - `mode: :explicit` - - `:"gpt-5-mini-2025-08-07"` + The breakpoint mode. Always `explicit`. - - `:"gpt-5-nano-2025-08-07"` + - `:explicit` - - `:"gpt-5-chat-latest"` + - `class BetaResponseInputImage` - - `:"gpt-4.1"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:"gpt-4.1-mini"` + - `detail: :low | :high | :auto | :original` - - `:"gpt-4.1-nano"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:"gpt-4.1-2025-04-14"` + - `:low` - - `:"gpt-4.1-mini-2025-04-14"` + - `:high` - - `:"gpt-4.1-nano-2025-04-14"` + - `:auto` - - `:"o4-mini"` + - `:original` - - `:"o4-mini-2025-04-16"` + - `type: :input_image` - - `:o3` + The type of the input item. Always `input_image`. - - `:"o3-2025-04-16"` + - `:input_image` - - `:"o3-mini"` + - `file_id: String` - - `:"o3-mini-2025-01-31"` + The ID of the file to be sent to the model. - - `:o1` + - `image_url: String` - - `:"o1-2024-12-17"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `:"o1-preview"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:"o1-preview-2024-09-12"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:"o1-mini"` + - `mode: :explicit` - - `:"o1-mini-2024-09-12"` + The breakpoint mode. Always `explicit`. - - `:"gpt-4o"` + - `:explicit` - - `:"gpt-4o-2024-11-20"` + - `class BetaResponseInputFile` - - `:"gpt-4o-2024-08-06"` + A file input to the model. - - `:"gpt-4o-2024-05-13"` + - `type: :input_file` - - `:"gpt-4o-audio-preview"` + The type of the input item. Always `input_file`. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `:input_file` - - `:"gpt-4o-audio-preview-2024-12-17"` + - `detail: :auto | :low | :high` - - `:"gpt-4o-audio-preview-2025-06-03"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `:"gpt-4o-mini-audio-preview"` + - `:auto` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `:low` - - `:"gpt-4o-search-preview"` + - `:high` - - `:"gpt-4o-mini-search-preview"` + - `file_data: String` - - `:"gpt-4o-search-preview-2025-03-11"` + The content of the file to be sent to the model. - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `file_id: String` - - `:"chatgpt-4o-latest"` + The ID of the file to be sent to the model. - - `:"codex-mini-latest"` + - `file_url: String` - - `:"gpt-4o-mini"` + The URL of the file to be sent to the model. - - `:"gpt-4o-mini-2024-07-18"` + - `filename: String` - - `:"gpt-4-turbo"` + The name of the file to be sent to the model. - - `:"gpt-4-turbo-2024-04-09"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:"gpt-4-0125-preview"` + Marks the exact end of a reusable 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-4-turbo-preview"` + - `mode: :explicit` - - `:"gpt-4-1106-preview"` + The breakpoint mode. Always `explicit`. - - `:"gpt-4-vision-preview"` + - `:explicit` - - `:"gpt-4"` + - `role: :user | :assistant | :system | :developer` - - `:"gpt-4-0314"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `:"gpt-4-0613"` + - `:user` - - `:"gpt-4-32k"` + - `:assistant` - - `:"gpt-4-32k-0314"` + - `:system` - - `:"gpt-4-32k-0613"` + - `:developer` - - `:"gpt-3.5-turbo"` + - `phase: :commentary | :final_answer` - - `:"gpt-3.5-turbo-16k"` + 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-3.5-turbo-0301"` + - `:commentary` - - `:"gpt-3.5-turbo-0613"` + - `:final_answer` - - `:"gpt-3.5-turbo-1106"` + - `type: :message` - - `:"gpt-3.5-turbo-0125"` + The type of the message input. Always `message`. - - `:"gpt-3.5-turbo-16k-0613"` + - `:message` - - `:"o1-pro"` + - `class Message` - - `:"o1-pro-2025-03-19"` + 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. - - `:"o3-pro"` + - `content: BetaResponseInputMessageContentList` - - `:"o3-pro-2025-06-10"` + A list of one or many input items to the model, containing different content + types. - - `:"o3-deep-research"` + - `role: :user | :system | :developer` - - `:"o3-deep-research-2025-06-26"` + The role of the message input. One of `user`, `system`, or `developer`. - - `:"o4-mini-deep-research"` + - `:user` - - `:"o4-mini-deep-research-2025-06-26"` + - `:system` - - `:"computer-use-preview"` + - `:developer` - - `:"computer-use-preview-2025-03-11"` + - `agent: Agent{ agent_name}` - - `:"gpt-5-codex"` + The agent that produced this item. - - `:"gpt-5-pro"` + - `agent_name: String` - - `:"gpt-5-pro-2025-10-06"` + The canonical name of the agent that produced this item. - - `:"gpt-5.1-codex-max"` + - `status: :in_progress | :completed | :incomplete` - - `String = String` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `object: :response` + - `:in_progress` - The object type of this resource - always set to `response`. + - `:completed` - - `:response` + - `:incomplete` - - `output: Array[BetaResponseOutputItem]` + - `type: :message` - An array of content items generated by the model. + The type of the message input. Always set to `message`. - - 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. + - `:message` - `class BetaResponseOutputMessage` An output message from the model. + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + 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. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + 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: Integer` + + 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` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `: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: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :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` + - `class BetaResponseFileSearchToolCall` 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. - - `class BetaResponseFunctionToolCall` + - `id: String` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The unique ID of the file search tool call. - - `class BetaResponseFunctionToolCallOutputItem` + - `queries: Array[String]` - - `id: String` + The queries used to search for files. - The unique ID of the function call tool output. + - `status: :in_progress | :searching | :completed | 2 more` - - `call_id: String` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The unique ID of the function tool call generated by the model. + - `:in_progress` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:searching` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `:completed` + + - `:incomplete` + + - `:failed` + + - `type: :file_search_call` + + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. 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 = String` - A string of the output of the function call. + - `Float = Float` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `UnionMember2 = bool` - Text, image, or file output of the function call. + - `file_id: String` - - `class BetaResponseInputText` + The unique ID of the file. - A text input to the model. + - `filename: String` - - `class BetaResponseInputImage` + The name of the file. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `score: Float` - - `class BetaResponseInputFile` + The relevance score of the file - a value between 0 and 1. - A file input to the model. + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + 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[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. - `status: :in_progress | :completed | :incomplete` @@ -77193,131 +88203,274 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :function_call_output` + - `type: :computer_call` - The type of the function tool call output. Always `function_call_output`. + The type of the computer call. Always `computer_call`. - - `:function_call_output` + - `:computer_call` - - `agent: Agent{ agent_name}` + - `action: BetaComputerAction` - The agent that produced this item. + A click action. - - `agent_name: String` + - `class Click` - The canonical name of the agent that produced this item. + A click action. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `button: :left | :right | :wheel | 2 more` - The execution context that produced this tool call. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class Direct` + - `:left` - - `type: :direct` + - `:right` - The caller type. Always `direct`. + - `:wheel` - - `:direct` + - `:back` - - `class Program` + - `:forward` - - `caller_id: String` + - `type: :click` - The call ID of the program item that produced this tool call. + Specifies the event type. For a click action, this property is always `click`. - - `type: :program` + - `:click` - The caller type. Always `program`. + - `x: Integer` - - `:program` + The x-coordinate where the click occurred. - - `created_by: String` + - `y_: Integer` - The identifier of the actor that created the item. + The y-coordinate where the click occurred. - - `class AgentMessage` + - `keys: Array[String]` - - `id: String` + The keys being held while clicking. - The unique ID of the agent message. + - `class DoubleClick` - - `author: String` + A double click action. - The sending agent identity. + - `keys: Array[String]` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + The keys being held while double-clicking. - Encrypted content sent between agents. + - `type: :double_click` - - `class BetaResponseInputText` + 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` - - `class BetaResponseOutputText` + - `x: Integer` - A text output from the model. + The x-coordinate where the double click occurred. - - `class Text` + - `y_: Integer` - A text content. + The y-coordinate where the double click occurred. - - `text: String` + - `class Drag` - - `type: :text` + A drag action. - - `:text` + - `path: Array[Path{ x, y_}]` - - `class SummaryText` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - A summary text from the model. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `text: String` + - `x: Integer` - A summary of the reasoning output from the model so far. + The x-coordinate. - - `type: :summary_text` + - `y_: Integer` - The type of the object. Always `summary_text`. + The y-coordinate. - - `:summary_text` + - `type: :drag` - - `class ReasoningText` + Specifies the event type. For a drag action, this property is always set to `drag`. - Reasoning text from the model. + - `:drag` + + - `keys: Array[String]` + + The keys being held while dragging the mouse. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `keys: Array[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` + + - `class Move` + + A mouse move action. + + - `type: :move` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `:move` + + - `x: Integer` + + The x-coordinate to move to. + + - `y_: Integer` + + The y-coordinate to move to. + + - `keys: Array[String]` + + The keys being held while moving the mouse. + + - `class Screenshot` + + A screenshot action. + + - `type: :screenshot` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `:screenshot` + + - `class Scroll` + + A scroll action. + + - `scroll_x: Integer` + + The horizontal scroll distance. + + - `scroll_y: Integer` + + The vertical scroll distance. + + - `type: :scroll` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class Type` + + An action to type in text. - `text: String` - The reasoning text from the model. + The text to type. - - `type: :reasoning_text` + - `type: :type` - The type of the reasoning text. Always `reasoning_text`. + Specifies the event type. For a type action, this property is always set to `type`. - - `:reasoning_text` + - `:type` - - `class BetaResponseOutputRefusal` + - `class Wait` - A refusal from the model. + A wait action. - - `class BetaResponseInputImage` + - `type: :wait` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class ComputerScreenshot` + - `:wait` - A screenshot of a computer. + - `actions: BetaComputerActionList` - - `detail: :low | :high | :auto | :original` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class Click` - - `:low` + A click action. - - `:high` + - `class DoubleClick` - - `:auto` + A double click action. - - `:original` + - `class Drag` + + A drag action. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `class Move` + + A mouse move action. + + - `class Screenshot` + + A screenshot action. + + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ComputerCallOutput` + + 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: String` @@ -77327,151 +88480,180 @@ puts(beta_compacted_response) The URL of the screenshot image. - - `type: :computer_screenshot` + - `type: :computer_call_output` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The type of the computer tool call output. Always `computer_call_output`. - - `:computer_screenshot` + - `:computer_call_output` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 computer tool call output. - - `mode: :explicit` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ 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` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :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` - - `class BetaResponseInputFile` + - `:incomplete` - A file input to the model. + - `class BetaResponseFunctionWebSearch` - - `class EncryptedContent` + 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. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `id: String` - - `encrypted_content: String` + The unique ID of the web search tool call. - Opaque encrypted content. + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `type: :encrypted_content` + 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 `encrypted_content`. + - `class Search` - - `:encrypted_content` + Action type "search" - Performs a web search query. - - `recipient: String` + - `type: :search` - The destination agent identity. + The action type. - - `type: :agent_message` + - `:search` - The type of the item. Always `agent_message`. + - `queries: Array[String]` - - `:agent_message` + The search queries. - - `agent: Agent{ agent_name}` + - `query: String` - The agent that produced this item. + The search query. - - `agent_name: String` + - `sources: Array[Source{ type, url}]` - The canonical name of the agent that produced this item. + The sources used in the search. - - `class MultiAgentCall` + - `type: :url` - - `id: String` + The type of source. Always `url`. - The unique ID of the multi-agent call item. + - `:url` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `url: String` - The multi-agent action to execute. + The URL of the source. - - `:spawn_agent` + - `class OpenPage` - - `:interrupt_agent` + Action type "open_page" - Opens a specific URL from search results. - - `:list_agents` + - `type: :open_page` - - `:send_message` + The action type. - - `:followup_task` + - `:open_page` - - `:wait_agent` + - `url: String` - - `arguments: String` + The URL opened by the model. - The JSON string of arguments generated for the action. + - `class FindInPage` - - `call_id: String` + Action type "find_in_page": Searches for a pattern within a loaded page. - The unique ID linking this call to its output. + - `pattern: String` - - `type: :multi_agent_call` + The pattern or text to search for within the page. - The type of the multi-agent call. Always `multi_agent_call`. + - `type: :find_in_page` - - `:multi_agent_call` + The action type. - - `agent: Agent{ agent_name}` + - `:find_in_page` - The agent that produced this item. + - `url: String` - - `agent_name: String` + The URL of the page searched for the pattern. - The canonical name of the agent that produced this item. + - `status: :in_progress | :searching | :completed | :failed` - - `class MultiAgentCallOutput` + The status of the web search tool call. - - `id: String` + - `:in_progress` - The unique ID of the multi-agent call output item. + - `:searching` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:completed` - The multi-agent action that produced this result. + - `:failed` - - `:spawn_agent` + - `type: :web_search_call` - - `:interrupt_agent` + The type of the web search tool call. Always `web_search_call`. - - `:list_agents` + - `:web_search_call` - - `:send_message` + - `agent: Agent{ agent_name}` - - `:followup_task` + The agent that produced this item. - - `:wait_agent` + - `agent_name: String` - - `call_id: String` + The canonical name of the agent that produced this item. - The unique ID of the multi-agent call. + - `class BetaResponseFunctionToolCall` - - `output: Array[BetaResponseOutputText]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Text output returned by the multi-agent action. + - `arguments: String` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + A JSON string of the arguments to pass to the function. - The annotations of the text output. + - `call_id: String` - - `text: String` + The unique ID of the function tool call generated by the model. - The text output from the model. + - `name: String` - - `type: :output_text` + The name of the function to run. - The type of the output text. Always `output_text`. + - `type: :function_call` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The type of the function tool call. Always `function_call`. - - `type: :multi_agent_call_output` + - `:function_call` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `id: String` - - `:multi_agent_call_output` + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -77481,190 +88663,180 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch` - - 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. - - - `class BetaResponseComputerToolCall` + - `caller_: Direct{ type} | Program{ caller_id, 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. + The execution context that produced this tool call. - - `class BetaResponseComputerToolCallOutputItem` + - `class Direct` - - `id: String` + - `type: :direct` - The unique ID of the computer call tool output. + - `:direct` - - `call_id: String` + - `class Program` - The ID of the computer tool call that produced the output. + - `caller_id: String` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The call ID of the program item that produced this tool call. - A computer screenshot image used with the computer use tool. + - `type: :program` - - `status: :completed | :incomplete | :failed | :in_progress` + - `:program` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `namespace: String` - - `:completed` + The namespace of the function to run. - - `:incomplete` + - `status: :in_progress | :completed | :incomplete` - - `:failed` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` - - `type: :computer_call_output` + - `:completed` - The type of the computer tool call output. Always `computer_call_output`. + - `:incomplete` - - `:computer_call_output` + - `class FunctionCallOutput` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + The output of a function 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 function tool call generated by the model. - The ID of the pending safety check. + - `output: String | BetaResponseFunctionCallOutputItemList` - - `code: String` + Text, image, or file output of the function tool call. - The type of the pending safety check. + - `String = String` - - `message: String` + A JSON string of the output of the function tool call. - Details about the pending safety check. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `agent: Agent{ agent_name}` + An array of content outputs (text, image, file) for the function tool call. - The agent that produced this item. + - `class BetaResponseInputTextContent` - - `agent_name: String` + A text input to the model. - The canonical name of the agent that produced this item. + - `text: String` - - `created_by: String` + The text input to the model. - The identifier of the actor that created the item. + - `type: :input_text` - - `class BetaResponseReasoningItem` + The type of the input item. Always `input_text`. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `:input_text` - - `class Program` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 program item. + - `mode: :explicit` - - `call_id: String` + The breakpoint mode. Always `explicit`. - The stable call ID of the program item. + - `:explicit` - - `code: String` + - `class BetaResponseInputImageContent` - The JavaScript source executed by programmatic tool calling. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `fingerprint: String` + - `type: :input_image` - Opaque program replay fingerprint that must be round-tripped. + The type of the input item. Always `input_image`. - - `type: :program` + - `:input_image` - The type of the item. Always `program`. + - `detail: :low | :high | :auto | :original` - - `:program` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `agent: Agent{ agent_name}` + - `:low` - The agent that produced this item. + - `:high` - - `agent_name: String` + - `:auto` - The canonical name of the agent that produced this item. + - `:original` - - `class ProgramOutput` + - `file_id: String` - - `id: String` + The ID of the file to be sent to the model. - The unique ID of the program output item. + - `image_url: String` - - `call_id: String` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The call ID of the program item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `result: 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 result produced by the program item. + - `mode: :explicit` - - `status: :completed | :incomplete` + The breakpoint mode. Always `explicit`. - The terminal status of the program output item. + - `:explicit` - - `:completed` + - `class BetaResponseInputFileContent` - - `:incomplete` + A file input to the model. - - `type: :program_output` + - `type: :input_file` - The type of the item. Always `program_output`. + The type of the input item. Always `input_file`. - - `:program_output` + - `:input_file` - - `agent: Agent{ agent_name}` + - `detail: :auto | :low | :high` - The agent that produced this item. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `agent_name: String` + - `:auto` - The canonical name of the agent that produced this item. + - `:low` - - `class BetaResponseToolSearchCall` + - `:high` - - `id: String` + - `file_data: String` - The unique ID of the tool search call item. + The base64-encoded data of the file to be sent to the model. - - `arguments: untyped` + - `file_id: String` - Arguments used for the tool search call. + The ID of the file to be sent to the model. - - `call_id: String` + - `file_url: String` - The unique ID of the tool search call generated by the model. + The URL of the file to be sent to the model. - - `execution: :server | :client` + - `filename: String` - Whether tool search was executed by the server or by the client. + The name of the file to be sent to the model. - - `:server` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:client` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `status: :in_progress | :completed | :incomplete` + - `mode: :explicit` - The status of the tool search call item that was recorded. + The breakpoint mode. Always `explicit`. - - `:in_progress` + - `:explicit` - - `:completed` + - `type: :function_call_output` - - `:incomplete` + The type of the function tool call output. Always `function_call_output`. - - `type: :tool_search_call` + - `:function_call_output` - The type of the item. Always `tool_search_call`. + - `id: String` - - `:tool_search_call` + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -77674,31 +88846,33 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `class BetaResponseToolSearchOutputItem` + - `class Direct` - - `id: String` + - `type: :direct` - The unique ID of the tool search output item. + The caller type. Always `direct`. - - `call_id: String` + - `:direct` - The unique ID of the tool search call generated by the model. + - `class Program` - - `execution: :server | :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`. + + - `:program` - `status: :in_progress | :completed | :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` @@ -77706,79 +88880,53 @@ puts(beta_compacted_response) - `:incomplete` - - `tools: Array[BetaTool]` - - The loaded tool definitions returned by tool search. - - - `class BetaFunctionTool` - - 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). - - - `class BetaFileSearchTool` - - 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). - - - `class BetaComputerTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool` - - 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). - - - `class Mcp` + - `class AgentMessage` - 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 message routed between agents. - - `class CodeInterpreter` + - `author: String` - A tool that runs Python code to help generate a response to a prompt. + The sending agent identity. - - `class ProgrammaticToolCalling` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `class ImageGeneration` + Plaintext, image, or encrypted content sent between agents. - A tool that generates images using the GPT image models. + - `class BetaResponseInputTextContent` - - `class LocalShell` + A text input to the model. - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseInputImageContent` - - `class BetaFunctionShellTool` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - A tool that allows the model to execute shell commands. + - `class EncryptedContent` - - `class BetaCustomTool` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - 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) + - `encrypted_content: String` - - `class BetaNamespaceTool` + Opaque encrypted content. - Groups function/custom tools under a shared namespace. + - `type: :encrypted_content` - - `class BetaToolSearchTool` + The type of the input item. Always `encrypted_content`. - Hosted or BYOT tool search configuration for deferred tools. + - `:encrypted_content` - - `class BetaWebSearchPreviewTool` + - `recipient: 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 destination agent identity. - - `class BetaApplyPatchTool` + - `type: :agent_message` - Allows the assistant to create, delete, or update files using unified diffs. + The item type. Always `agent_message`. - - `type: :tool_search_output` + - `:agent_message` - The type of the item. Always `tool_search_output`. + - `id: String` - - `:tool_search_output` + The unique ID of this agent message item. - `agent: Agent{ agent_name}` @@ -77788,177 +88936,171 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class AdditionalTools` + - `class MultiAgentCall` - - `id: String` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The unique ID of the additional tools item. + The multi-agent action that was executed. - - `role: :unknown | :user | :assistant | 5 more` + - `:spawn_agent` - The role that provided the additional tools. + - `:interrupt_agent` - - `:unknown` + - `:list_agents` - - `:user` + - `:send_message` - - `:assistant` + - `:followup_task` - - `:system` + - `:wait_agent` - - `:critic` + - `arguments: String` - - `:discriminator` + The action arguments as a JSON string. - - `:developer` + - `call_id: String` - - `:tool` + The unique ID linking this call to its output. - - `tools: Array[BetaTool]` + - `type: :multi_agent_call` - The additional tool definitions made available at this item. + The item type. Always `multi_agent_call`. - - `class BetaFunctionTool` + - `:multi_agent_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). + - `id: String` - - `class BetaFileSearchTool` + The unique ID of this multi-agent 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). + - `agent: Agent{ agent_name}` - - `class BetaComputerTool` + 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` - - `class BetaComputerUsePreviewTool` + 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). + - `class MultiAgentCallOutput` - - `class BetaWebSearchTool` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - 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 multi-agent action that produced this result. - - `class Mcp` + - `:spawn_agent` - 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). + - `:interrupt_agent` - - `class CodeInterpreter` + - `:list_agents` - A tool that runs Python code to help generate a response to a prompt. + - `:send_message` - - `class ProgrammaticToolCalling` + - `:followup_task` - - `class ImageGeneration` + - `:wait_agent` - A tool that generates images using the GPT image models. + - `call_id: String` - - `class LocalShell` + The unique ID of the multi-agent call. - A tool that allows the model to execute shell commands in a local environment. + - `output: Array[Output{ text, type, annotations}]` - - `class BetaFunctionShellTool` + Text output returned by the multi-agent action. - A tool that allows the model to execute shell commands. + - `text: String` - - `class BetaCustomTool` + The text 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) + - `type: :output_text` - - `class BetaNamespaceTool` + The content type. Always `output_text`. - Groups function/custom tools under a shared namespace. + - `:output_text` - - `class BetaToolSearchTool` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - Hosted or BYOT tool search configuration for deferred tools. + Citations associated with the text content. - - `class BetaWebSearchPreviewTool` + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_id: String` - - `class BetaApplyPatchTool` + The ID of the file. - Allows the assistant to create, delete, or update files using unified diffs. + - `filename: String` - - `type: :additional_tools` + The filename of the file cited. - The type of the item. Always `additional_tools`. + - `index: Integer` - - `:additional_tools` + The index of the file in the list of files. - - `agent: Agent{ agent_name}` + - `type: :file_citation` - The agent that produced this item. + The citation type. Always `file_citation`. - - `agent_name: String` + - `:file_citation` - The canonical name of the agent that produced this item. + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `class BetaResponseCompactionItem` + - `end_index: Integer` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The index of the last character of the citation in the message. - - `id: String` + - `start_index: Integer` - The unique ID of the compaction item. + The index of the first character of the citation in the message. - - `encrypted_content: String` + - `title: String` - The encrypted content that was produced by compaction. + The title of the cited resource. - - `type: :compaction` + - `type: :url_citation` - The type of the item. Always `compaction`. + The citation type. Always `url_citation`. - - `:compaction` + - `:url_citation` - - `agent: Agent{ agent_name}` + - `url: String` - The agent that produced this item. + The URL of the cited resource. - - `agent_name: String` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - The canonical name of the agent that produced this item. + - `container_id: String` - - `created_by: String` + The ID of the container. - The identifier of the actor that created the item. + - `end_index: Integer` - - `class ImageGenerationCall` + The index of the last character of the citation in the message. - An image generation request made by the model. + - `file_id: String` - - `id: String` + The ID of the container file. - The unique ID of the image generation call. + - `filename: String` - - `result: String` + The filename of the container file cited. - The generated image encoded in base64. + - `start_index: Integer` - - `status: :in_progress | :completed | :generating | :failed` + The index of the first character of the citation in the message. - The status of the image generation call. + - `type: :container_file_citation` - - `:in_progress` + The citation type. Always `container_file_citation`. - - `:completed` + - `:container_file_citation` - - `:generating` + - `type: :multi_agent_call_output` - - `:failed` + The item type. Always `multi_agent_call_output`. - - `type: :image_generation_call` + - `:multi_agent_call_output` - The type of the image generation call. Always `image_generation_call`. + - `id: String` - - `:image_generation_call` + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -77968,55 +89110,45 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` - - A tool call to run code. - - - `class LocalShellCall` - - A tool call to run a command on the local shell. - - - `id: String` - - The unique ID of the local shell call. + - `class ToolSearchCall` - - `action: Action{ command, env, type, 3 more}` + - `arguments: untyped` - Execute a shell command on the server. + The arguments supplied to the tool search call. - - `command: Array[String]` + - `type: :tool_search_call` - The command to run. + The item type. Always `tool_search_call`. - - `env: Hash[Symbol, String]` + - `:tool_search_call` - Environment variables to set for the command. + - `id: String` - - `type: :exec` + The unique ID of this tool search call. - The type of the local shell action. Always `exec`. + - `agent: Agent{ agent_name}` - - `:exec` + The agent that produced this item. - - `timeout_ms: Integer` + - `agent_name: String` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: String` + - `call_id: String` - Optional user to run the command as. + The unique ID of the tool search call generated by the model. - - `working_directory: String` + - `execution: :server | :client` - Optional working directory to run the command in. + Whether tool search was executed by the server or by the client. - - `call_id: String` + - `:server` - The unique ID of the local shell tool call generated by the model. + - `:client` - `status: :in_progress | :completed | :incomplete` - The status of the local shell call. + The status of the tool search call. - `:in_progress` @@ -78024,1577 +89156,1533 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :local_shell_call` + - `class BetaResponseToolSearchOutputItemParam` - The type of the local shell call. Always `local_shell_call`. + - `tools: Array[BetaTool]` - - `:local_shell_call` + The loaded tool definitions returned by the tool search output. - - `agent: Agent{ agent_name}` + - `class BetaFunctionTool` - The agent that produced this item. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the function to call. - - `class LocalShellCallOutput` + - `parameters: Hash[Symbol, untyped]` - The output of a local shell tool call. + A JSON schema object describing the parameters of the function. - - `id: String` + - `strict: bool` - The unique ID of the local shell tool call generated by the model. + Whether strict parameter validation is enforced for this function tool. - - `output: String` + - `type: :function` - A JSON string of the output of the local shell tool call. + The type of the function tool. Always `function`. - - `type: :local_shell_call_output` + - `:function` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:local_shell_call_output` + The tool invocation context(s). - - `agent: Agent{ agent_name}` + - `:direct` - The agent that produced this item. + - `:programmatic` - - `agent_name: String` + - `defer_loading: bool` - The canonical name of the agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `status: :in_progress | :completed | :incomplete` + - `description: String` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A description of the function. Used by the model to determine whether or not to call the function. - - `:in_progress` + - `output_schema: Hash[Symbol, untyped]` - - `:completed` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `:incomplete` + - `class BetaFileSearchTool` - - `class BetaResponseFunctionShellToolCall` + 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 executes one or more shell commands in a managed environment. + - `type: :file_search` - - `id: String` + The type of the file search tool. Always `file_search`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `:file_search` - - `action: Action{ commands, max_output_length, timeout_ms}` + - `vector_store_ids: Array[String]` - The shell commands and limits that describe how to run the tool call. + The IDs of the vector stores to search. - - `commands: Array[String]` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `max_output_length: Integer` + A filter to apply. - Optional maximum number of characters to return from each command. + - `class ComparisonFilter` - - `timeout_ms: Integer` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Optional timeout in milliseconds for the commands. + - `key: String` - - `call_id: String` + The key to compare against the value. - The unique ID of the shell tool call generated by the model. + - `type: :eq | :ne | :gt | 5 more` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Represents the use of a local environment to perform shell actions. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class BetaResponseLocalEnvironment` + - `:eq` - Represents the use of a local environment to perform shell actions. + - `:ne` - - `type: :local` + - `:gt` - The environment type. Always `local`. + - `:gte` - - `:local` + - `:lt` - - `class BetaResponseContainerReference` + - `:lte` - Represents a container created with /v1/containers. + - `:in` - - `container_id: String` + - `:nin` - - `type: :container_reference` + - `value: String | Float | bool | Array[String | Float]` - The environment type. Always `container_reference`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `:container_reference` + - `String = String` - - `status: :in_progress | :completed | :incomplete` + - `Float = Float` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `UnionMember2 = bool` - - `:in_progress` + - `UnionMember3 = Array[String | Float]` - - `:completed` + - `String = String` - - `:incomplete` + - `Float = Float` - - `type: :shell_call` + - `class CompoundFilter` - The type of the item. Always `shell_call`. + Combine multiple filters using `and` or `or`. - - `:shell_call` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `agent: Agent{ agent_name}` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The agent that produced this item. + - `class ComparisonFilter` - - `agent_name: String` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The canonical name of the agent that produced this item. + - `key: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The key to compare against the value. - The execution context that produced this tool call. + - `type: :eq | :ne | :gt | 5 more` - - `class Direct` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: :direct` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `:direct` + - `:eq` - - `class Program` + - `:ne` - - `caller_id: String` + - `:gt` - The call ID of the program item that produced this tool call. + - `:gte` - - `type: :program` + - `:lt` - - `:program` + - `:lte` - - `created_by: String` + - `:in` - The ID of the entity that created this tool call. + - `:nin` - - `class BetaResponseFunctionShellToolCallOutput` + - `value: String | Float | bool | Array[String | Float]` - The output of a shell tool call that was emitted. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: String` + - `String = String` - The unique ID of the shell call output. Populated when this item is returned via API. + - `Float = Float` - - `call_id: String` + - `UnionMember2 = bool` - The unique ID of the shell tool call generated by the model. + - `UnionMember3 = Array[String | Float]` - - `max_output_length: Integer` + - `String = String` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `Float = Float` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `UnionMember1 = untyped` - An array of shell call output contents + - `type: :and | :or` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + Type of operation: `and` or `or`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `:and` - - `class Timeout` + - `:or` - Indicates that the shell call exceeded its configured time limit. + - `max_num_results: Integer` - - `type: :timeout` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The outcome type. Always `timeout`. + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - - `:timeout` + Ranking options for search. - - `class Exit` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - Indicates that the shell commands finished and returned an exit code. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `exit_code: Integer` + - `embedding_weight: Float` - Exit code from the shell process. + The weight of the embedding in the reciprocal ranking fusion. - - `type: :exit` + - `text_weight: Float` - The outcome type. Always `exit`. + The weight of the text in the reciprocal ranking fusion. - - `:exit` + - `ranker: :auto | :"default-2024-11-15"` - - `stderr: String` + The ranker to use for the file search. - The standard error output that was captured. + - `:auto` - - `stdout: String` + - `:"default-2024-11-15"` - The standard output that was captured. + - `score_threshold: Float` - - `created_by: 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 identifier of the actor that created the item. + - `class BetaComputerTool` - - `status: :in_progress | :completed | :incomplete` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `type: :computer` - - `:in_progress` + The type of the computer tool. Always `computer`. - - `:completed` + - `:computer` - - `:incomplete` + - `class BetaComputerUsePreviewTool` - - `type: :shell_call_output` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the shell call output. Always `shell_call_output`. + - `display_height: Integer` - - `:shell_call_output` + The height of the computer display. - - `agent: Agent{ agent_name}` + - `display_width: Integer` - The agent that produced this item. + The width of the computer display. - - `agent_name: String` + - `environment: :windows | :mac | :linux | 2 more` - The canonical name of the agent that produced this item. + The type of computer environment to control. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:windows` - The execution context that produced this tool call. + - `:mac` - - `class Direct` + - `:linux` - - `type: :direct` + - `:ubuntu` - - `:direct` + - `:browser` - - `class Program` + - `type: :computer_use_preview` - - `caller_id: String` + The type of the computer use tool. Always `computer_use_preview`. - The call ID of the program item that produced this tool call. + - `:computer_use_preview` - - `type: :program` + - `class BetaWebSearchTool` - - `:program` + 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). - - `created_by: String` + - `type: :web_search | :web_search_2025_08_26` - The identifier of the actor that created the item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `class BetaResponseApplyPatchToolCall` + - `:web_search` - A tool call that applies file diffs by creating, deleting, or updating files. + - `:web_search_2025_08_26` - - `id: String` + - `filters: Filters{ allowed_domains}` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Filters for the search. - - `call_id: String` + - `allowed_domains: Array[String]` - The unique ID of the apply patch 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. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `search_context_size: :low | :medium | :high` - - `class CreateFile` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Instruction describing how to create a file via the apply_patch tool. + - `:low` - - `diff: String` + - `:medium` - Diff to apply. + - `:high` - - `path: String` + - `user_location: UserLocation{ city, country, region, 2 more}` - Path of the file to create. + The approximate location of the user. - - `type: :create_file` + - `city: String` - Create a new file with the provided diff. + Free text input for the city of the user, e.g. `San Francisco`. - - `:create_file` + - `country: String` - - `class DeleteFile` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Instruction describing how to delete a file via the apply_patch tool. + - `region: String` - - `path: String` + Free text input for the region of the user, e.g. `California`. - Path of the file to delete. + - `timezone: String` - - `type: :delete_file` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Delete the specified file. + - `type: :approximate` - - `:delete_file` + The type of location approximation. Always `approximate`. - - `class UpdateFile` + - `:approximate` - Instruction describing how to update a file via the apply_patch tool. + - `class Mcp` - - `diff: 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). - Diff to apply. + - `server_label: String` - - `path: String` + A label for this MCP server, used to identify it in tool calls. - Path of the file to update. + - `type: :mcp` - - `type: :update_file` + The type of the MCP tool. Always `mcp`. - Update an existing file with the provided diff. + - `:mcp` - - `:update_file` + - `allowed_callers: Array[:direct | :programmatic]` - - `status: :in_progress | :completed` + The tool invocation context(s). - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:direct` - - `:in_progress` + - `:programmatic` - - `:completed` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `type: :apply_patch_call` + List of allowed tool names or a filter object. - The type of the item. Always `apply_patch_call`. + - `McpAllowedTools = Array[String]` - - `:apply_patch_call` + A string array of allowed tool names - - `agent: Agent{ agent_name}` + - `class McpToolFilter` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `agent_name: String` + - `read_only: bool` - The canonical name of the agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `tool_names: Array[String]` - The execution context that produced this tool call. + List of allowed tool names. - - `class Direct` + - `authorization: String` - - `type: :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. + + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 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` - - `:direct` + - `:connector_dropbox` - - `class Program` + - `: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: String` + - `:connector_outlookemail` - The ID of the entity that created this tool call. + - `:connector_sharepoint` - - `class BetaResponseApplyPatchToolCallOutput` + - `defer_loading: bool` - The output emitted by an apply patch tool call. + Whether this MCP tool is deferred and discovered via tool search. - - `id: String` + - `headers: Hash[Symbol, String]` - The unique ID of the apply patch tool 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: McpToolApprovalFilter{ always, never} | :always | :never` - The unique ID of the apply patch tool call generated by the model. + Specify which of the MCP server's tools require approval. - - `status: :completed | :failed` + - `class McpToolApprovalFilter` - The status of the apply patch tool call output. One of `completed` or `failed`. + 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: Always{ read_only, tool_names}` - - `:failed` + A filter object to specify which tools are allowed. - - `type: :apply_patch_call_output` + - `read_only: bool` - The type of the item. Always `apply_patch_call_output`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:apply_patch_call_output` + - `tool_names: Array[String]` - - `agent: Agent{ agent_name}` + List of allowed tool names. - The agent that produced this item. + - `never: Never{ 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: bool` - - `caller_: Direct{ type} | Program{ 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: Array[String]` - - `class Direct` + List of allowed tool names. - - `type: :direct` + - `McpToolApprovalSetting = :always | :never` - - `: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. - - `class Program` + - `:always` - - `caller_id: String` + - `:never` - The call ID of the program item that produced this tool call. + - `server_description: String` - - `type: :program` + Optional description of the MCP server, used to provide more context. - - `:program` + - `server_url: String` - - `created_by: String` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The ID of the entity that created this tool call output. + - `tunnel_id: String` - - `output: 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. - Optional textual output returned by the apply patch tool. + - `class CodeInterpreter` - - `class McpCall` + A tool that runs Python code to help generate a response to a prompt. - An invocation of a tool on an MCP server. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `id: String` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The unique ID of the tool call. + - `String = String` - - `arguments: String` + The container ID. - A JSON string of the arguments passed to the tool. + - `class CodeInterpreterToolAuto` - - `name: String` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The name of the tool that was run. + - `type: :auto` - - `server_label: String` + Always `auto`. - The label of the MCP server running the tool. + - `:auto` - - `type: :mcp_call` + - `file_ids: Array[String]` - The type of the item. Always `mcp_call`. + An optional list of uploaded files to make available to your code. - - `:mcp_call` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `agent: Agent{ 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"` - - `approval_request_id: String` + - `:"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. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `error: String` + Network access policy for the container. - The error from the tool call, if any. + - `class BetaContainerNetworkPolicyDisabled` - - `output: String` + - `type: :disabled` - The output from the tool call. + Disable outbound network access. Always `disabled`. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `:disabled` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `class BetaContainerNetworkPolicyAllowlist` - - `:in_progress` + - `allowed_domains: Array[String]` - - `:completed` + A list of allowed domains when type is `allowlist`. - - `:incomplete` + - `type: :allowlist` - - `:calling` + Allow outbound network access only to specified domains. Always `allowlist`. - - `:failed` + - `:allowlist` - - `class McpListTools` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - A list of tools available on an MCP server. + Optional domain-scoped secrets for allowlisted domains. - - `id: String` + - `domain: String` - The unique ID of the list. + The domain associated with the secret. - - `server_label: String` + - `name: String` - The label of the MCP server. + The name of the secret to inject for the domain. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `value: String` - The tools available on the server. + The secret value to inject for the domain. - - `input_schema: untyped` + - `type: :code_interpreter` - The JSON schema describing the tool's input. + The type of the code interpreter tool. Always `code_interpreter`. - - `name: String` + - `:code_interpreter` - The name of the tool. + - `allowed_callers: Array[:direct | :programmatic]` - - `annotations: untyped` + The tool invocation context(s). - Additional annotations about the tool. + - `:direct` - - `description: String` + - `:programmatic` - The description of the tool. + - `class ProgrammaticToolCalling` - - `type: :mcp_list_tools` + - `type: :programmatic_tool_calling` - The type of the item. Always `mcp_list_tools`. + The type of the tool. Always `programmatic_tool_calling`. - - `:mcp_list_tools` + - `:programmatic_tool_calling` - - `agent: Agent{ agent_name}` + - `class ImageGeneration` - The agent that produced this item. + A tool that generates images using the GPT image models. - - `agent_name: String` + - `type: :image_generation` - The canonical name of the agent that produced this item. + The type of the image generation tool. Always `image_generation`. - - `error: String` + - `:image_generation` - Error message if the server could not list tools. + - `action: :generate | :edit | :auto` - - `class McpApprovalRequest` + Whether to generate a new image or edit an existing image. Default: `auto`. - A request for human approval of a tool invocation. + - `:generate` - - `id: String` + - `:edit` - The unique ID of the approval request. + - `:auto` - - `arguments: String` + - `background: :transparent | :opaque | :auto` - A JSON string of arguments for the tool. + 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. - - `name: 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 name of the tool to run. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `server_label: String` + - `:transparent` - The label of the MCP server making the request. + - `:opaque` - - `type: :mcp_approval_request` + - `:auto` - The type of the item. Always `mcp_approval_request`. + - `input_fidelity: :high | :low` - - `:mcp_approval_request` + 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: Agent{ agent_name}` + - `:high` - The agent that produced this item. + - `:low` - - `agent_name: String` + - `input_image_mask: InputImageMask{ 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). - - `class McpApprovalResponse` + - `file_id: String` - A response to an MCP approval request. + File ID for the mask image. - - `id: String` + - `image_url: String` - The unique ID of the approval response + Base64-encoded mask image. - - `approval_request_id: String` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - The ID of the approval request being answered. + The image generation model to use. Default: `gpt-image-1`. - - `approve: bool` + - `String = String` - Whether the request was approved. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `type: :mcp_approval_response` + The image generation model to use. Default: `gpt-image-1`. - The type of the item. Always `mcp_approval_response`. + - `:"gpt-image-1"` - - `:mcp_approval_response` + - `:"gpt-image-1-mini"` - - `agent: Agent{ agent_name}` + - `:"gpt-image-2"` - The agent that produced this item. + - `:"gpt-image-2-2026-04-21"` - - `agent_name: String` + - `:"gpt-image-1.5"` - The canonical name of the agent that produced this item. + - `:"chatgpt-image-latest"` - - `reason: String` + - `moderation: :auto | :low` - Optional reason for the decision. + Moderation level for the generated image. Default: `auto`. - - `class BetaResponseCustomToolCall` + - `:auto` - A call to a custom tool created by the model. + - `:low` - - `class BetaResponseCustomToolCallOutputItem` + - `output_compression: Integer` - The output of a custom tool call from your code, being sent back to the model. + Compression level for the output image. Default: 100. - - `id: String` + - `output_format: :png | :webp | :jpeg` - The unique ID of the custom tool call output item. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `status: :in_progress | :completed | :incomplete` + - `:png` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:webp` - - `:in_progress` + - `:jpeg` - - `:completed` + - `partial_images: Integer` - - `:incomplete` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `created_by: String` + - `quality: :low | :medium | :high | :auto` - The identifier of the actor that created the item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `parallel_tool_calls: bool` + - `:low` - Whether to allow the model to run tool calls in parallel. + - `:medium` - - `temperature: Float` + - `: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. + - `:auto` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - 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 size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `BetaToolChoiceOptions = :none | :auto | :required` + - `String = String` - Controls which (if any) tool is called by the model. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - `none` means the model will not call any tool and instead generates a 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`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `:"1024x1024"` - `required` means the model must call one or more tools. + - `:"1024x1536"` - - `:none` + - `:"1536x1024"` - `:auto` - - `:required` + - `class LocalShell` - - `class BetaToolChoiceAllowed` + A tool that allows the model to execute shell commands in a local environment. - Constrains the tools available to the model to a pre-defined set. + - `type: :local_shell` - - `mode: :auto | :required` + The type of the local shell tool. Always `local_shell`. - Constrains the tools available to the model to a pre-defined set. + - `:local_shell` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `class BetaFunctionShellTool` - `required` requires the model to call one or more of the allowed tools. + A tool that allows the model to execute shell commands. - - `:auto` + - `type: :shell` - - `:required` + The type of the shell tool. Always `shell`. - - `tools: Array[Hash[Symbol, untyped]]` + - `:shell` - A list of tool definitions that the model should be allowed to call. + - `allowed_callers: Array[:direct | :programmatic]` - For the Responses API, the list of tool definitions might look like: + The tool invocation context(s). - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `:direct` - - `type: :allowed_tools` + - `:programmatic` - Allowed tool configuration type. Always `allowed_tools`. + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `:allowed_tools` + - `class BetaContainerAuto` - - `class BetaToolChoiceTypes` + - `type: :container_auto` - 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). + Automatically creates a container for this request - - `type: :file_search | :web_search_preview | :computer | 5 more` + - `:container_auto` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `file_ids: Array[String]` - Allowed values are: + An optional list of uploaded files to make available to your code. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `:file_search` + The memory limit for the container. - - `:web_search_preview` + - `:"1g"` - - `:computer` + - `:"4g"` - - `:computer_use_preview` + - `:"16g"` - - `:computer_use` + - `:"64g"` - - `:web_search_preview_2025_03_11` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:image_generation` + Network access policy for the container. - - `:code_interpreter` + - `class BetaContainerNetworkPolicyDisabled` - - `class BetaToolChoiceFunction` + - `class BetaContainerNetworkPolicyAllowlist` - Use this option to force the model to call a specific function. + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `name: String` + An optional list of skills referenced by id or inline data. - The name of the function to call. + - `class BetaSkillReference` - - `type: :function` + - `skill_id: String` - For function calling, the type is always `function`. + The ID of the referenced skill. - - `:function` + - `type: :skill_reference` - - `class BetaToolChoiceMcp` + References a skill created with the /v1/skills endpoint. - Use this option to force the model to call a specific tool on a remote MCP server. + - `:skill_reference` - - `server_label: String` + - `version: String` - The label of the MCP server to use. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: :mcp` + - `class BetaInlineSkill` - For MCP tools, the type is always `mcp`. + - `description: String` - - `:mcp` + The description of the skill. - `name: String` - The name of the tool to call on the server. - - - `class BetaToolChoiceCustom` + The name of the skill. - Use this option to force the model to call a specific custom tool. + - `source: BetaInlineSkillSource` - - `name: String` + Inline skill payload - The name of the custom tool to call. + - `data: String` - - `type: :custom` + Base64-encoded skill zip bundle. - For custom tool calling, the type is always `custom`. + - `media_type: :"application/zip"` - - `:custom` + The media type of the inline skill payload. Must be `application/zip`. - - `class BetaSpecificProgrammaticToolCallingParam` + - `:"application/zip"` - - `type: :programmatic_tool_calling` + - `type: :base64` - The tool to call. Always `programmatic_tool_calling`. + The type of the inline skill source. Must be `base64`. - - `:programmatic_tool_calling` + - `:base64` - - `class BetaToolChoiceApplyPatch` + - `type: :inline` - Forces the model to call the apply_patch tool when executing a tool call. + Defines an inline skill for this request. - - `type: :apply_patch` + - `:inline` - The tool to call. Always `apply_patch`. + - `class BetaLocalEnvironment` - - `:apply_patch` + - `type: :local` - - `class BetaToolChoiceShell` + Use a local computer environment. - Forces the model to call the shell tool when a tool call is required. + - `:local` - - `type: :shell` + - `skills: Array[BetaLocalSkill]` - The tool to call. Always `shell`. + An optional list of skills. - - `:shell` + - `description: String` - - `tools: Array[BetaTool]` + The description of the skill. - 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. + - `name: String` - We support the following categories of tools: + The name of the skill. - - **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. + - `path: String` - - `class BetaFunctionTool` + The path to the directory containing the skill. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaContainerReference` - - `class BetaFileSearchTool` + - `container_id: String` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The ID of the referenced container. - - `class BetaComputerTool` + - `type: :container_reference` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + References a container created with the /v1/containers endpoint - - `class BetaComputerUsePreviewTool` + - `:container_reference` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class BetaCustomTool` - - `class BetaWebSearchTool` + 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) - 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). + - `name: String` - - `class Mcp` + The name of the custom tool, used to identify it in tool calls. - 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: :custom` - - `class CodeInterpreter` + The type of the custom tool. Always `custom`. - A tool that runs Python code to help generate a response to a prompt. + - `:custom` - - `class ProgrammaticToolCalling` + - `allowed_callers: Array[:direct | :programmatic]` - - `class ImageGeneration` + The tool invocation context(s). - A tool that generates images using the GPT image models. + - `:direct` - - `class LocalShell` + - `:programmatic` - A tool that allows the model to execute shell commands in a local environment. + - `defer_loading: bool` - - `class BetaFunctionShellTool` + Whether this tool should be deferred and discovered via tool search. - A tool that allows the model to execute shell commands. + - `description: String` - - `class BetaCustomTool` + Optional description of the custom tool, used to provide more context. - 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) + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `class BetaNamespaceTool` + The input format for the custom tool. Default is unconstrained text. - Groups function/custom tools under a shared namespace. + - `class Text` - - `class BetaToolSearchTool` + Unconstrained free-form text. - Hosted or BYOT tool search configuration for deferred tools. + - `type: :text` - - `class BetaWebSearchPreviewTool` + Unconstrained text format. Always `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). + - `:text` - - `class BetaApplyPatchTool` + - `class Grammar` - Allows the assistant to create, delete, or update files using unified diffs. + A grammar defined by the user. - - `top_p: Float` + - `definition: 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 grammar definition. - We generally recommend altering this or `temperature` but not both. + - `syntax: :lark | :regex` - - `background: bool` + The syntax of the grammar definition. One of `lark` or `regex`. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `:lark` - - `completed_at: Float` + - `:regex` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `type: :grammar` - - `conversation: Conversation{ id}` + Grammar format. Always `grammar`. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `:grammar` - - `id: String` + - `class BetaNamespaceTool` - The unique ID of the conversation that this response was associated with. + Groups function/custom tools under a shared namespace. - - `max_output_tokens: Integer` + - `description: 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). + A description of the namespace shown to the model. - - `max_tool_calls: Integer` + - `name: 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 namespace name used in tool calls (for example, `crm`). - - `moderation: Moderation{ input, output}` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - Moderation results for the response input and output, if moderated completions were requested. + The function/custom tools available inside this namespace. - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `class Function` - Moderation for the response input. + - `name: String` - - `class ModerationResult` + - `type: :function` - A moderation result produced for the response input or output. + - `:function` - - `categories: Hash[Symbol, bool]` + - `allowed_callers: Array[:direct | :programmatic]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The tool invocation context(s). - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `:direct` - Which modalities of input are reflected by the score for each category. + - `:programmatic` - - `:text` + - `defer_loading: bool` - - `:image` + Whether this function should be deferred and discovered via tool search. - - `category_scores: Hash[Symbol, Float]` + - `description: String` - A dictionary of moderation categories to scores. + - `output_schema: Hash[Symbol, untyped]` - - `flagged: bool` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A boolean indicating whether the content was flagged by any category. + - `parameters: untyped` - - `model: String` + - `strict: bool` - The moderation model that produced this result. + 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: :moderation_result` + - `class BetaCustomTool` - The object type, which was always `moderation_result` for successful moderation results. + 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) - - `:moderation_result` + - `type: :namespace` - - `class Error` + The type of the tool. Always `namespace`. - An error produced while attempting moderation for the response input or output. + - `:namespace` - - `code: String` + - `class BetaToolSearchTool` - The error code. + Hosted or BYOT tool search configuration for deferred tools. - - `message: String` + - `type: :tool_search` - The error message. + The type of the tool. Always `tool_search`. - - `type: :error` + - `:tool_search` - The object type, which was always `error` for moderation failures. + - `description: String` - - `:error` + Description shown to the model for a client-executed tool search tool. - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `execution: :server | :client` - Moderation for the response output. + Whether tool search is executed by the server or by the client. - - `class ModerationResult` + - `:server` - A moderation result produced for the response input or output. + - `:client` - - `categories: Hash[Symbol, bool]` + - `parameters: untyped` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Parameter schema for a client-executed tool search tool. - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `class BetaWebSearchPreviewTool` - Which modalities of input are reflected by the score for each category. + 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` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `:image` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `category_scores: Hash[Symbol, Float]` + - `:web_search_preview` - A dictionary of moderation categories to scores. + - `:web_search_preview_2025_03_11` - - `flagged: bool` + - `search_content_types: Array[:text | :image]` - A boolean indicating whether the content was flagged by any category. + - `:text` - - `model: String` + - `:image` - The moderation model that produced this result. + - `search_context_size: :low | :medium | :high` - - `type: :moderation_result` + High 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 object type, which was always `moderation_result` for successful moderation results. + - `:low` - - `:moderation_result` + - `:medium` - - `class Error` + - `:high` - An error produced while attempting moderation for the response input or output. + - `user_location: UserLocation{ type, city, country, 2 more}` - - `code: String` + The user's location. - The error code. + - `type: :approximate` - - `message: String` + The type of location approximation. Always `approximate`. - The error message. + - `:approximate` - - `type: :error` + - `city: String` - The object type, which was always `error` for moderation failures. + Free text input for the city of the user, e.g. `San Francisco`. - - `:error` + - `country: String` - - `previous_response_id: 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 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`. + - `region: String` - - `prompt: BetaResponsePrompt` + Free text input for the region of the user, e.g. `California`. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `timezone: String` - - `id: String` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique identifier of the prompt template to use. + - `class BetaApplyPatchTool` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + Allows the assistant to create, delete, or update files using unified diffs. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `type: :apply_patch` - - `String = String` + The type of the tool. Always `apply_patch`. - - `class BetaResponseInputText` + - `:apply_patch` - A text input to the model. + - `allowed_callers: Array[:direct | :programmatic]` - - `class BetaResponseInputImage` + The tool invocation context(s). - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:direct` - - `class BetaResponseInputFile` + - `:programmatic` - A file input to the model. + - `type: :tool_search_output` - - `version: String` + The item type. Always `tool_search_output`. - Optional version of the prompt template. + - `:tool_search_output` - - `prompt_cache_key: String` + - `id: 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 unique ID of this tool search output. - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `agent: Agent{ agent_name}` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The agent that produced this item. - - `mode: :implicit | :explicit` + - `agent_name: String` - Whether implicit prompt-cache breakpoints were enabled. + The canonical name of the agent that produced this item. - - `:implicit` + - `call_id: String` - - `:explicit` + The unique ID of the tool search call generated by the model. - - `ttl: :"30m"` + - `execution: :server | :client` - The minimum lifetime applied to each cache breakpoint. + Whether tool search was executed by the server or by the client. - - `:"30m"` + - `:server` - - `prompt_cache_retention: :in_memory | :"24h"` + - `:client` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `status: :in_progress | :completed | :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. + The status of the tool search output. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `:in_progress` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `:completed` - - `:in_memory` + - `:incomplete` - - `:"24h"` + - `class AdditionalTools` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `role: :developer` - **gpt-5 and o-series models only** + The role that provided the additional tools. Only `developer` is supported. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `:developer` - - `context: :auto | :current_turn | :all_turns` + - `tools: Array[BetaTool]` - 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 list of additional tools made available at this item. - - `:auto` + - `class BetaFunctionTool` - - `:current_turn` + 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). - - `:all_turns` + - `class BetaFileSearchTool` - - `effort: :none | :minimal | :low | 4 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). - 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. + - `class BetaComputerTool` - - `:none` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:minimal` + - `class BetaComputerUsePreviewTool` - - `:low` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:medium` + - `class BetaWebSearchTool` - - `:high` + 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). - - `:xhigh` + - `class Mcp` - - `:max` + 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). - - `generate_summary: :auto | :concise | :detailed` + - `class CodeInterpreter` - **Deprecated:** use `summary` instead. + A tool that runs Python code to help generate a response to a prompt. - 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`. + - `class ProgrammaticToolCalling` - - `:auto` + - `class ImageGeneration` - - `:concise` + A tool that generates images using the GPT image models. - - `:detailed` + - `class LocalShell` - - `mode: String | :standard | :pro` + A tool that allows the model to execute shell commands in a local environment. - Controls the reasoning execution mode for the request. + - `class BetaFunctionShellTool` - When returned on a response, this is the effective execution mode. + A tool that allows the model to execute shell commands. - - `String = String` + - `class BetaCustomTool` - - `Mode = :standard | :pro` + 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) - Controls the reasoning execution mode for the request. + - `class BetaNamespaceTool` - When returned on a response, this is the effective execution mode. + Groups function/custom tools under a shared namespace. - - `:standard` + - `class BetaToolSearchTool` - - `:pro` + Hosted or BYOT tool search configuration for deferred tools. - - `summary: :auto | :concise | :detailed` + - `class BetaWebSearchPreviewTool` - 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`. + 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). - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `class BetaApplyPatchTool` - - `:auto` + Allows the assistant to create, delete, or update files using unified diffs. - - `:concise` + - `type: :additional_tools` - - `:detailed` + The item type. Always `additional_tools`. - - `safety_identifier: String` + - `:additional_tools` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `id: String` - - `service_tier: :auto | :default | :flex | 2 more` + The unique ID of this additional tools item. - Specifies the processing type used for serving the request. + - `agent: Agent{ 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` + - `class BetaResponseReasoningItem` - - `:flex` + 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). - - `:scale` + - `id: String` - - `:priority` + The unique identifier of the reasoning content. - - `status: BetaResponseStatus` + - `summary: Array[Summary{ text, type}]` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Reasoning summary content. - - `:completed` + - `text: String` - - `:failed` + A summary of the reasoning output from the model so far. - - `:in_progress` + - `type: :summary_text` - - `:cancelled` + The type of the object. Always `summary_text`. - - `:queued` + - `:summary_text` - - `:incomplete` + - `type: :reasoning` - - `text: BetaResponseTextConfig` + The type of the object. Always `reasoning`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `:reasoning` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `agent: Agent{ agent_name}` - - `format_: 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](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - The default format is `{ "type": "text" }` with no additional options. + - `content: Array[Content{ text, type}]` - **Not recommended for gpt-4o and newer models:** + Reasoning text 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. + - `text: String` - - `class Text` + The reasoning text from the model. - Default response format. Used to generate text responses. + - `type: :reasoning_text` - - `type: :text` + The type of the reasoning text. Always `reasoning_text`. - The type of response format being defined. Always `text`. + - `:reasoning_text` - - `:text` + - `encrypted_content: String` - - `class BetaResponseFormatTextJSONSchemaConfig` + 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](https://platform.openai.com/docs/guides/structured-outputs). + - `status: :in_progress | :completed | :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 response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `:in_progress` - - `schema: Hash[Symbol, untyped]` + - `:completed` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `:incomplete` - - `type: :json_schema` + - `class BetaResponseCompactionItemParam` - The type of response format being defined. Always `json_schema`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:json_schema` + - `encrypted_content: String` - - `description: String` + The encrypted content of the compaction summary. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `type: :compaction` - - `strict: bool` + The type of the item. Always `compaction`. - 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). + - `:compaction` - - `class JSONObject` + - `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 ID of the compaction item. - - `type: :json_object` + - `agent: Agent{ agent_name}` - The type of response format being defined. Always `json_object`. + The agent that produced this item. - - `:json_object` + - `agent_name: String` - - `verbosity: :low | :medium | :high` + The canonical name of 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`. + - `class ImageGenerationCall` - - `:low` + An image generation request made by the model. - - `:medium` + - `id: String` - - `:high` + The unique ID of the image generation call. - - `top_logprobs: Integer` + - `result: 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 generated image encoded in base64. - - `truncation: :auto | :disabled` + - `status: :in_progress | :completed | :generating | :failed` - The truncation strategy to use for the model response. + The status of the image generation 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. + - `:in_progress` - - `:auto` + - `:completed` - - `:disabled` + - `:generating` - - `usage: BetaResponseUsage` + - `:failed` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `type: :image_generation_call` - - `input_tokens: Integer` + The type of the image generation call. Always `image_generation_call`. - The number of input tokens. + - `:image_generation_call` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `agent: Agent{ agent_name}` - A detailed breakdown of the input tokens. + The agent that produced this item. - - `cache_write_tokens: Integer` + - `agent_name: String` - The number of input tokens that were written to the cache. + The canonical name of the agent that produced this item. - - `cached_tokens: Integer` + - `class BetaResponseCodeInterpreterToolCall` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + A tool call to run code. - - `output_tokens: Integer` + - `id: String` - The number of output tokens. + The unique ID of the code interpreter tool call. - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `code: String` - A detailed breakdown of the output tokens. + The code to run, or null if not available. - - `reasoning_tokens: Integer` + - `container_id: String` - The number of reasoning tokens. + The ID of the container used to run the code. - - `total_tokens: Integer` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - The total number of tokens used. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `user: String` + - `class Logs` - 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 logs output from the code interpreter. - - `sequence_number: Integer` + - `logs: String` - The sequence number of this event. + The logs output from the code interpreter. - - `type: :"response.failed"` + - `type: :logs` - The type of the event. Always `response.failed`. + The type of the output. Always `logs`. - - `:"response.failed"` + - `:logs` - - `agent: Agent{ agent_name}` + - `class Image` - The agent that owns this multi-agent streaming event. + The image output from the code interpreter. - - `agent_name: String` + - `type: :image` - The canonical name of the agent that produced this item. + The type of the output. Always `image`. -### Beta Response File Search Call Completed Event + - `:image` -- `class BetaResponseFileSearchCallCompletedEvent` + - `url: String` - Emitted when a file search call is completed (results found). + The URL of the image output from the code interpreter. - - `item_id: String` + - `status: :in_progress | :completed | :incomplete | 2 more` - The ID of the output item that the file search call is initiated. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `output_index: Integer` + - `:in_progress` - The index of the output item that the file search call is initiated. + - `:completed` - - `sequence_number: Integer` + - `:incomplete` - The sequence number of this event. + - `:interpreting` - - `type: :"response.file_search_call.completed"` + - `:failed` - The type of the event. Always `response.file_search_call.completed`. + - `type: :code_interpreter_call` - - `:"response.file_search_call.completed"` + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `:code_interpreter_call` - `agent: Agent{ 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 + - `class LocalShellCall` -- `class BetaResponseFileSearchCallInProgressEvent` + A tool call to run a command on the local shell. - Emitted when a file search call is initiated. + - `id: String` - - `item_id: String` + The unique ID of the local shell call. - The ID of the output item that the file search call is initiated. + - `action: Action{ command, env, type, 3 more}` - - `output_index: Integer` + Execute a shell command on the server. - The index of the output item that the file search call is initiated. + - `command: Array[String]` - - `sequence_number: Integer` + The command to run. - The sequence number of this event. + - `env: Hash[Symbol, String]` - - `type: :"response.file_search_call.in_progress"` + Environment variables to set for the command. - The type of the event. Always `response.file_search_call.in_progress`. + - `type: :exec` - - `:"response.file_search_call.in_progress"` + The type of the local shell action. Always `exec`. - - `agent: Agent{ agent_name}` + - `:exec` - The agent that owns this multi-agent streaming event. + - `timeout_ms: Integer` - - `agent_name: String` + Optional timeout in milliseconds for the command. - The canonical name of the agent that produced this item. + - `user: String` -### Beta Response File Search Call Searching Event + Optional user to run the command as. -- `class BetaResponseFileSearchCallSearchingEvent` + - `working_directory: String` - Emitted when a file search is currently searching. + Optional working directory to run the command in. - - `item_id: String` + - `call_id: String` - The ID of the output item that the file search call is initiated. + The unique ID of the local shell tool call generated by the model. - - `output_index: Integer` + - `status: :in_progress | :completed | :incomplete` - The index of the output item that the file search call is searching. + The status of the local shell call. - - `sequence_number: Integer` + - `:in_progress` - The sequence number of this event. + - `:completed` - - `type: :"response.file_search_call.searching"` + - `:incomplete` - The type of the event. Always `response.file_search_call.searching`. + - `type: :local_shell_call` - - `:"response.file_search_call.searching"` + The type of the local shell call. Always `local_shell_call`. + + - `:local_shell_call` - `agent: Agent{ 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 Tool Call - -- `class BetaResponseFileSearchToolCall` + - `class LocalShellCallOutput` - 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 output of a local shell tool call. - `id: String` - The unique ID of the file search tool call. - - - `queries: Array[String]` - - The queries used to search for files. - - - `status: :in_progress | :searching | :completed | 2 more` - - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, - - - `:in_progress` - - - `:searching` - - - `:completed` + The unique ID of the local shell tool call generated by the model. - - `:incomplete` + - `output: String` - - `:failed` + A JSON string of the output of the local shell tool call. - - `type: :file_search_call` + - `type: :local_shell_call_output` - The type of the file search tool call. Always `file_search_call`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:file_search_call` + - `:local_shell_call_output` - `agent: Agent{ agent_name}` @@ -79604,678 +90692,657 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `status: :in_progress | :completed | :incomplete` - The results of the file search tool call. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `attributes: Hash[Symbol, String | Float | bool]` + - `:in_progress` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `:completed` - - `String = String` + - `:incomplete` - - `Float = Float` + - `class ShellCall` - - `UnionMember2 = bool` + A tool representing a request to execute one or more shell commands. - - `file_id: String` + - `action: Action{ commands, max_output_length, timeout_ms}` - The unique ID of the file. + The shell commands and limits that describe how to run the tool call. - - `filename: String` + - `commands: Array[String]` - The name of the file. + Ordered shell commands for the execution environment to run. - - `score: Float` + - `max_output_length: Integer` - The relevance score of the file - a value between 0 and 1. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `text: String` + - `timeout_ms: Integer` - The text that was retrieved from the file. + Maximum wall-clock time in milliseconds to allow the shell commands to run. -### Beta Response Format Text Config + - `call_id: String` -- `BetaResponseFormatTextConfig = Text{ type} | BetaResponseFormatTextJSONSchemaConfig | JSONObject{ type}` + The unique ID of the shell tool call generated by the model. - An object specifying the format that the model must output. + - `type: :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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the item. Always `shell_call`. - The default format is `{ "type": "text" }` with no additional options. + - `:shell_call` - **Not recommended for gpt-4o and newer models:** + - `id: 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 unique ID of the shell tool call. Populated when this item is returned via API. - - `class Text` + - `agent: Agent{ agent_name}` - Default response format. Used to generate text responses. + The agent that produced this item. - - `type: :text` + - `agent_name: String` - The type of response format being defined. Always `text`. + The canonical name of the agent that produced this item. - - `:text` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class BetaResponseFormatTextJSONSchemaConfig` + The execution context 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). + - `class Direct` - - `name: String` + - `type: :direct` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The caller type. Always `direct`. - - `schema: Hash[Symbol, untyped]` + - `:direct` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `class Program` - - `type: :json_schema` + - `caller_id: String` - The type of response format being defined. Always `json_schema`. + The call ID of the program item that produced this tool call. - - `:json_schema` + - `type: :program` - - `description: String` + The caller type. Always `program`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:program` - - `strict: bool` + - `environment: BetaLocalEnvironment | BetaContainerReference` - 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 environment to execute the shell commands in. - - `class JSONObject` + - `class BetaLocalEnvironment` - 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. + - `class BetaContainerReference` - - `type: :json_object` + - `status: :in_progress | :completed | :incomplete` - The type of response format being defined. Always `json_object`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:json_object` + - `:in_progress` -### Beta Response Format Text JSON Schema Config + - `:completed` -- `class BetaResponseFormatTextJSONSchemaConfig` + - `:incomplete` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `class ShellCallOutput` - - `name: String` + The streamed output items emitted by a 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. + - `call_id: String` - - `schema: Hash[Symbol, untyped]` + The unique ID of the shell tool call generated by the model. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - - `type: :json_schema` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The type of response format being defined. Always `json_schema`. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `:json_schema` + The exit or timeout outcome associated with this shell call. - - `description: String` + - `class Timeout` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Indicates that the shell call exceeded its configured time limit. - - `strict: bool` + - `type: :timeout` - 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 outcome type. Always `timeout`. -### Beta Response Function Call Arguments Delta Event + - `:timeout` -- `class BetaResponseFunctionCallArgumentsDeltaEvent` + - `class Exit` - Emitted when there is a partial function-call arguments delta. + Indicates that the shell commands finished and returned an exit code. - - `delta: String` + - `exit_code: Integer` - The function-call arguments delta that is added. + The exit code returned by the shell process. - - `item_id: String` + - `type: :exit` - The ID of the output item that the function-call arguments delta is added to. + The outcome type. Always `exit`. - - `output_index: Integer` + - `:exit` - The index of the output item that the function-call arguments delta is added to. + - `stderr: String` - - `sequence_number: Integer` + Captured stderr output for the shell call. - The sequence number of this event. + - `stdout: String` - - `type: :"response.function_call_arguments.delta"` + Captured stdout output for the shell call. - The type of the event. Always `response.function_call_arguments.delta`. + - `type: :shell_call_output` - - `:"response.function_call_arguments.delta"` + The type of the item. Always `shell_call_output`. + + - `:shell_call_output` + + - `id: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: Agent{ 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 - -- `class BetaResponseFunctionCallArgumentsDoneEvent` - - Emitted when function-call arguments are finalized. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `arguments: String` + The execution context that produced this tool call. - The function-call arguments. + - `class Direct` - - `item_id: String` + - `type: :direct` - The ID of the item. + The caller type. Always `direct`. - - `name: String` + - `:direct` - The name of the function that was called. + - `class Program` - - `output_index: Integer` + - `caller_id: String` - The index of the output item. + The call ID of the program item that produced this tool call. - - `sequence_number: Integer` + - `type: :program` - The sequence number of this event. + The caller type. Always `program`. - - `type: :"response.function_call_arguments.done"` + - `:program` - - `:"response.function_call_arguments.done"` + - `max_output_length: Integer` - - `agent: Agent{ agent_name}` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The agent that owns this multi-agent streaming event. + - `status: :in_progress | :completed | :incomplete` - - `agent_name: String` + The status of the shell call output. - The canonical name of the agent that produced this item. + - `:in_progress` -### Beta Response Function Call Output Item + - `:completed` -- `BetaResponseFunctionCallOutputItem = BetaResponseInputTextContent | BetaResponseInputImageContent | BetaResponseInputFileContent` + - `:incomplete` - A piece of message content, such as text, an image, or a file. + - `class ApplyPatchCall` - - `class BetaResponseInputTextContent` + A tool call representing a request to create, delete, or update files using diff patches. - 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. + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `type: :input_text` + The specific create, delete, or update instruction for the apply_patch tool call. - The type of the input item. Always `input_text`. + - `class CreateFile` - - `:input_text` + Instruction for creating a new file via the apply_patch tool. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `diff: 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. + Unified diff content to apply when creating the file. - - `mode: :explicit` + - `path: String` - The breakpoint mode. Always `explicit`. + Path of the file to create relative to the workspace root. - - `:explicit` + - `type: :create_file` - - `class BetaResponseInputImageContent` + The operation type. Always `create_file`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:create_file` - - `type: :input_image` + - `class DeleteFile` - The type of the input item. Always `input_image`. + Instruction for deleting an existing file via the apply_patch tool. - - `:input_image` + - `path: String` - - `detail: :low | :high | :auto | :original` + Path of the file to delete relative to the workspace root. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: :delete_file` - - `:low` + The operation type. Always `delete_file`. - - `:high` + - `:delete_file` - - `:auto` + - `class UpdateFile` - - `:original` + Instruction for updating an existing file via the apply_patch tool. - - `file_id: String` + - `diff: String` - The ID of the file to be sent to the model. + Unified diff content to apply to the existing file. - - `image_url: String` + - `path: String` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Path of the file to update relative to the workspace root. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `type: :update_file` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The operation type. Always `update_file`. - - `mode: :explicit` + - `:update_file` - The breakpoint mode. Always `explicit`. + - `status: :in_progress | :completed` - - `:explicit` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class BetaResponseInputFileContent` + - `:in_progress` - A file input to the model. + - `:completed` - - `type: :input_file` + - `type: :apply_patch_call` - The type of the input item. Always `input_file`. + The type of the item. Always `apply_patch_call`. - - `:input_file` + - `:apply_patch_call` - - `detail: :auto | :low | :high` + - `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. Populated when this item is returned via API. - - `:auto` + - `agent: Agent{ agent_name}` - - `:low` + The agent that produced this item. - - `:high` + - `agent_name: String` - - `file_data: String` + The canonical name of the agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `file_id: String` + The execution context that produced this tool call. - The ID of the file to be sent to the model. + - `class Direct` - - `file_url: String` + - `type: :direct` - The URL of the file to be sent to the model. + The caller type. Always `direct`. - - `filename: String` + - `:direct` - The name of the file to be sent to the model. + - `class Program` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` -### Beta Response Function Call Output Item List + - `class ApplyPatchCallOutput` -- `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + The streamed output emitted by an apply patch tool call. - An array of content outputs (text, image, file) for the function tool call. + - `call_id: String` - - `class BetaResponseInputTextContent` + The unique ID of the apply patch tool call generated by the model. - A text input to the model. + - `status: :completed | :failed` - - `text: String` + The status of the apply patch tool call output. One of `completed` or `failed`. - The text input to the model. + - `:completed` - - `type: :input_text` + - `:failed` - The type of the input item. Always `input_text`. + - `type: :apply_patch_call_output` - - `:input_text` + The type of the item. Always `apply_patch_call_output`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `: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. + - `id: String` - - `mode: :explicit` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The breakpoint mode. Always `explicit`. + - `agent: Agent{ agent_name}` - - `:explicit` + The agent that produced this item. - - `class BetaResponseInputImageContent` + - `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. - - `type: :input_image` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The type of the input item. Always `input_image`. + The execution context that produced this tool call. - - `:input_image` + - `class Direct` - - `detail: :low | :high | :auto | :original` + - `type: :direct` - 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 `direct`. - - `:low` + - `:direct` - - `:high` + - `class Program` - - `:auto` + - `caller_id: String` - - `:original` + The call ID of the program item that produced this tool call. - - `file_id: String` + - `type: :program` - The ID of the file to be sent to the model. + The caller type. Always `program`. - - `image_url: String` + - `:program` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `output: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class McpListTools` - - `mode: :explicit` + A list of tools available on an MCP server. - The breakpoint mode. Always `explicit`. + - `id: String` - - `:explicit` + The unique ID of the list. - - `class BetaResponseInputFileContent` + - `server_label: String` - A file input to the model. + The label of the MCP server. - - `type: :input_file` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - The type of the input item. Always `input_file`. + The tools available on the server. - - `:input_file` + - `input_schema: untyped` - - `detail: :auto | :low | :high` + The JSON schema describing the tool's input. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `name: String` - - `:auto` + The name of the tool. - - `:low` + - `annotations: untyped` - - `:high` + Additional annotations about the tool. - - `file_data: String` + - `description: String` - The base64-encoded data of the file to be sent to the model. + The description of the tool. - - `file_id: String` + - `type: :mcp_list_tools` - The ID of the file to be sent to the model. + The type of the item. Always `mcp_list_tools`. - - `file_url: String` + - `:mcp_list_tools` - The URL of the file to be sent to the model. + - `agent: Agent{ agent_name}` - - `filename: String` + The agent that produced this item. - The name of the file to be sent to the model. + - `agent_name: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. + - `error: String` - - `mode: :explicit` + Error message if the server could not list tools. - The breakpoint mode. Always `explicit`. + - `class McpApprovalRequest` - - `:explicit` + A request for human approval of a tool invocation. -### Beta Response Function Shell Call Output Content + - `id: String` -- `class BetaResponseFunctionShellCallOutputContent` + The unique ID of the approval request. - Captured stdout and stderr for a portion of a shell tool call output. + - `arguments: String` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + A JSON string of arguments for the tool. - The exit or timeout outcome associated with this shell call. + - `name: String` - - `class Timeout` + The name of the tool to run. - Indicates that the shell call exceeded its configured time limit. + - `server_label: String` - - `type: :timeout` + The label of the MCP server making the request. - The outcome type. Always `timeout`. + - `type: :mcp_approval_request` - - `:timeout` + The type of the item. Always `mcp_approval_request`. - - `class Exit` + - `:mcp_approval_request` - Indicates that the shell commands finished and returned an exit code. + - `agent: Agent{ agent_name}` - - `exit_code: Integer` + The agent that produced this item. - The exit code returned by the shell process. + - `agent_name: String` - - `type: :exit` + The canonical name of the agent that produced this item. - The outcome type. Always `exit`. + - `class McpApprovalResponse` - - `:exit` + A response to an MCP approval request. - - `stderr: String` + - `approval_request_id: String` - Captured stderr output for the shell call. + The ID of the approval request being answered. - - `stdout: String` + - `approve: bool` - Captured stdout output for the shell call. + Whether the request was approved. -### Beta Response Function Shell Tool Call + - `type: :mcp_approval_response` -- `class BetaResponseFunctionShellToolCall` + The type of the item. Always `mcp_approval_response`. - A tool call that executes one or more shell commands in a managed environment. + - `:mcp_approval_response` - `id: String` - The unique ID of the shell tool call. Populated when this item is returned via API. + The unique ID of the approval response - - `action: Action{ commands, max_output_length, timeout_ms}` + - `agent: Agent{ agent_name}` - The shell commands and limits that describe how to run the tool call. + The agent that produced this item. - - `commands: Array[String]` + - `agent_name: String` - - `max_output_length: Integer` + The canonical name of the agent that produced this item. - Optional maximum number of characters to return from each command. + - `reason: String` - - `timeout_ms: Integer` + Optional reason for the decision. - Optional timeout in milliseconds for the commands. + - `class McpCall` - - `call_id: String` + An invocation of a tool on an MCP server. - The unique ID of the shell tool call generated by the model. + - `id: String` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + The unique ID of the tool call. - Represents the use of a local environment to perform shell actions. + - `arguments: String` - - `class BetaResponseLocalEnvironment` + A JSON string of the arguments passed to the tool. - Represents the use of a local environment to perform shell actions. + - `name: String` - - `type: :local` + The name of the tool that was run. - The environment type. Always `local`. + - `server_label: String` - - `:local` + The label of the MCP server running the tool. - - `class BetaResponseContainerReference` + - `type: :mcp_call` - Represents a container created with /v1/containers. + The type of the item. Always `mcp_call`. - - `container_id: String` + - `:mcp_call` - - `type: :container_reference` + - `agent: Agent{ agent_name}` - The environment type. Always `container_reference`. + The agent that produced this item. - - `:container_reference` + - `agent_name: String` - - `status: :in_progress | :completed | :incomplete` + The canonical name of the agent that produced this item. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `approval_request_id: String` - - `:in_progress` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `:completed` + - `error: String` - - `:incomplete` + The error from the tool call, if any. - - `type: :shell_call` + - `output: String` - The type of the item. Always `shell_call`. + The output from the tool call. - - `:shell_call` + - `status: :in_progress | :completed | :incomplete | 2 more` - - `agent: Agent{ agent_name}` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The agent that produced this item. + - `:in_progress` - - `agent_name: String` + - `:completed` - The canonical name of the agent that produced this item. + - `:incomplete` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:calling` - The execution context that produced this tool call. + - `:failed` - - `class Direct` + - `class BetaResponseCustomToolCallOutput` - - `type: :direct` + The output of a custom tool call from your code, being sent back to the model. - - `:direct` + - `call_id: String` - - `class Program` + The call ID, used to map this custom tool call output to a custom tool call. - - `caller_id: String` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The call ID of the program item that produced this tool call. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: :program` + - `String = String` - - `:program` + A string of the output of the custom tool call. - - `created_by: String` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The ID of the entity that created this tool call. + Text, image, or file output of the custom tool call. -### Beta Response Function Shell Tool Call Output + - `class BetaResponseInputText` -- `class BetaResponseFunctionShellToolCallOutput` + A text input to the model. - The output of a shell tool call that was emitted. + - `class BetaResponseInputImage` - - `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 call output. Populated when this item is returned via API. + - `class BetaResponseInputFile` - - `call_id: String` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: :custom_tool_call_output` - - `max_output_length: Integer` + The type of the custom tool call output. Always `custom_tool_call_output`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `:custom_tool_call_output` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `id: String` - An array of shell call output contents + The unique ID of the custom tool call output in the OpenAI platform. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `agent: Agent{ agent_name}` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The agent that produced this item. - - `class Timeout` + - `agent_name: String` - Indicates that the shell call exceeded its configured time limit. + The canonical name of the agent that produced this item. - - `type: :timeout` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The outcome type. Always `timeout`. + The execution context that produced this tool call. - - `:timeout` + - `class Direct` - - `class Exit` + - `type: :direct` - Indicates that the shell commands finished and returned an exit code. + The caller type. Always `direct`. - - `exit_code: Integer` + - `:direct` - Exit code from the shell process. + - `class Program` - - `type: :exit` + - `caller_id: String` - The outcome type. Always `exit`. + The call ID of the program item that produced this tool call. - - `:exit` + - `type: :program` - - `stderr: String` + The caller type. Always `program`. - The standard error output that was captured. + - `:program` - - `stdout: String` + - `class BetaResponseCustomToolCall` - The standard output that was captured. + A call to a custom tool created by the model. - - `created_by: 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. - - `status: :in_progress | :completed | :incomplete` + - `input: String` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The input for the custom tool call generated by the model. - - `:in_progress` + - `name: String` - - `:completed` + The name of the custom tool being called. - - `:incomplete` + - `type: :custom_tool_call` - - `type: :shell_call_output` + The type of the custom tool call. Always `custom_tool_call`. - The type of the shell call output. Always `shell_call_output`. + - `:custom_tool_call` - - `:shell_call_output` + - `id: String` + + The unique ID of the custom tool call in the OpenAI platform. - `agent: Agent{ agent_name}` @@ -80305,38 +91372,35 @@ puts(beta_compacted_response) - `:program` - - `created_by: String` - - The identifier of the actor that created the item. + - `namespace: String` -### Beta Response Function Tool Call + The namespace of the custom tool being called. -- `class BetaResponseFunctionToolCall` + - `class CompactionTrigger` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Compacts the current context. Must be the final input item. - - `arguments: String` + - `type: :compaction_trigger` - A JSON string of the arguments to pass to the function. + The type of the item. Always `compaction_trigger`. - - `call_id: String` + - `:compaction_trigger` - The unique ID of the function tool call generated by the model. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the function to run. + - `agent_name: String` - - `type: :function_call` + The canonical name of the agent that produced this item. - The type of the function tool call. Always `function_call`. + - `class ItemReference` - - `:function_call` + An internal identifier for an item to reference. - `id: String` - The unique ID of the function tool call. + The ID of the item to reference. - `agent: Agent{ agent_name}` @@ -80346,91 +91410,112 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `type: :item_reference` - The execution context that produced this tool call. + The type of item to reference. Always `item_reference`. - - `class Direct` + - `:item_reference` - - `type: :direct` + - `class Program` - - `:direct` + - `id: String` - - `class Program` + The unique ID of this program item. - - `caller_id: String` + - `call_id: String` - The call ID of the program item that produced this tool call. + The stable call ID of the program item. - - `type: :program` + - `code: String` - - `:program` + The JavaScript source executed by programmatic tool calling. - - `namespace: String` + - `fingerprint: String` - The namespace of the function to run. + Opaque program replay fingerprint that must be round-tripped. - - `status: :in_progress | :completed | :incomplete` + - `type: :program` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The item type. Always `program`. - - `:in_progress` + - `:program` - - `:completed` + - `agent: Agent{ agent_name}` - - `:incomplete` + The agent that produced this item. -### Beta Response Function Tool Call Item + - `agent_name: String` -- `class BetaResponseFunctionToolCallItem` + The canonical name of the agent that produced this item. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class ProgramOutput` - `id: String` - The unique ID of the function tool call. + The unique ID of this program output item. - - `status: :in_progress | :completed | :incomplete` + - `call_id: String` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The call ID of the program item. - - `:in_progress` + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. - `:completed` - `:incomplete` - - `created_by: String` + - `type: :program_output` - The identifier of the actor that created the item. + The item type. Always `program_output`. -### Beta Response Function Tool Call Output Item + - `:program_output` -- `class BetaResponseFunctionToolCallOutputItem` + - `agent: Agent{ agent_name}` - - `id: String` + The agent that produced this item. - The unique ID of the function call tool output. + - `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. +### Beta Response Input Audio - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` +- `class BetaResponseInputAudio` - The output from the function call generated by your code. - Can be a string or an list of output content. + An audio input to the model. - - `String = String` + - `input_audio: InputAudio{ data, format_}` - A string of the output of the function call. + - `data: String` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + Base64-encoded audio data. - Text, image, or file output of the function call. + - `format_: :mp3 | :wav` + + The format of the audio data. Currently supported formats are `mp3` and + `wav`. + + - `:mp3` + + - `:wav` + + - `type: :input_audio` + + The type of the input item. Always `input_audio`. + + - `:input_audio` + +### Beta Response Input Content + +- `BetaResponseInputContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile` + + A text input to the model. - `class BetaResponseInputText` @@ -80542,398 +91627,195 @@ puts(beta_compacted_response) - `:explicit` - - `status: :in_progress | :completed | :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 function tool call output. Always `function_call_output`. - - - `:function_call_output` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `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: String` - - The identifier of the actor that created the item. - -### Beta Response Function Web Search - -- `class BetaResponseFunctionWebSearch` - - 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: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). - - - `class Search` - - Action type "search" - Performs a web search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `query: String` - - The search query. - - - `sources: Array[Source{ type, url}]` - - The sources used in the search. - - - `type: :url` - - The type of source. Always `url`. - - - `:url` - - - `url: String` - - The URL of the source. - - - `class OpenPage` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: :open_page` - - The action type. - - - `:open_page` - - - `url: String` - - The URL opened by the model. - - - `class FindInPage` - - 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 | :searching | :completed | :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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - -### Beta Response Image Gen Call Completed Event - -- `class BetaResponseImageGenCallCompletedEvent` - - Emitted when an image generation tool call has completed and the final image is available. - - - `item_id: String` - - The unique identifier of the image generation item being processed. - - - `output_index: Integer` - - The index of the output item in the response's output array. - - - `sequence_number: Integer` - - The sequence number of this event. - - - `type: :"response.image_generation_call.completed"` - - The type of the event. Always 'response.image_generation_call.completed'. - - - `:"response.image_generation_call.completed"` - - - `agent: Agent{ agent_name}` - - The agent that owns this multi-agent streaming event. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - -### Beta Response Image Gen Call Generating Event - -- `class BetaResponseImageGenCallGeneratingEvent` - - Emitted when an image generation tool call is actively generating an image (intermediate state). - - - `item_id: String` - - The unique identifier of the image generation item being processed. - - - `output_index: Integer` - - The index of the output item in the response's output array. +### Beta Response Input File - - `sequence_number: Integer` +- `class BetaResponseInputFile` - The sequence number of the image generation item being processed. + A file input to the model. - - `type: :"response.image_generation_call.generating"` + - `type: :input_file` - The type of the event. Always 'response.image_generation_call.generating'. + The type of the input item. Always `input_file`. - - `:"response.image_generation_call.generating"` + - `:input_file` - - `agent: Agent{ agent_name}` + - `detail: :auto | :low | :high` - The agent that owns this multi-agent streaming 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`. - - `agent_name: String` + - `:auto` - The canonical name of the agent that produced this item. + - `:low` -### Beta Response Image Gen Call In Progress Event + - `:high` -- `class BetaResponseImageGenCallInProgressEvent` + - `file_data: String` - Emitted when an image generation tool call is in progress. + The content of the file to be sent to the model. - - `item_id: String` + - `file_id: String` - The unique identifier of the image generation item being processed. + The ID of the file to be sent to the model. - - `output_index: Integer` + - `file_url: String` - The index of the output item in the response's output array. + The URL of the file to be sent to the model. - - `sequence_number: Integer` + - `filename: String` - The sequence number of the image generation item being processed. + The name of the file to be sent to the model. - - `type: :"response.image_generation_call.in_progress"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The type of the event. Always 'response.image_generation_call.in_progress'. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:"response.image_generation_call.in_progress"` + - `mode: :explicit` - - `agent: Agent{ agent_name}` + The breakpoint mode. Always `explicit`. - The agent that owns this multi-agent streaming event. + - `:explicit` - - `agent_name: String` +### Beta Response Input File Content - The canonical name of the agent that produced this item. +- `class BetaResponseInputFileContent` -### Beta Response Image Gen Call Partial Image Event + A file input to the model. -- `class BetaResponseImageGenCallPartialImageEvent` + - `type: :input_file` - Emitted when a partial image is available during image generation streaming. + The type of the input item. Always `input_file`. - - `item_id: String` + - `:input_file` - The unique identifier of the image generation item being processed. + - `detail: :auto | :low | :high` - - `output_index: Integer` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The index of the output item in the response's output array. + - `:auto` - - `partial_image_b64: String` + - `:low` - Base64-encoded partial image data, suitable for rendering as an image. + - `:high` - - `partial_image_index: Integer` + - `file_data: String` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + The base64-encoded data of the file to be sent to the model. - - `sequence_number: Integer` + - `file_id: String` - The sequence number of the image generation item being processed. + The ID of the file to be sent to the model. - - `type: :"response.image_generation_call.partial_image"` + - `file_url: String` - The type of the event. Always 'response.image_generation_call.partial_image'. + The URL of the file to be sent to the model. - - `:"response.image_generation_call.partial_image"` + - `filename: String` - - `agent: Agent{ agent_name}` + The name of the file to be sent to the model. - The agent that owns this multi-agent streaming event. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` -### Beta Response In Progress Event + The breakpoint mode. Always `explicit`. -- `class BetaResponseInProgressEvent` + - `:explicit` - Emitted when the response is in progress. +### Beta Response Input Image - - `response: BetaResponse` +- `class BetaResponseInputImage` - The response that is in progress. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: String` + - `detail: :low | :high | :auto | :original` - Unique identifier for this Response. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `created_at: Float` + - `:low` - Unix timestamp (in seconds) of when this Response was created. + - `:high` - - `error: BetaResponseError` + - `:auto` - An error object returned when the model fails to generate a Response. + - `:original` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `type: :input_image` - The error code for the response. + The type of the input item. Always `input_image`. - - `:server_error` + - `:input_image` - - `:rate_limit_exceeded` + - `file_id: String` - - `:invalid_prompt` + The ID of the file to be sent to the model. - - `:bio_policy` + - `image_url: String` - - `:vector_store_timeout` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `:invalid_image` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:invalid_image_format` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:invalid_base64_image` + - `mode: :explicit` - - `:invalid_image_url` + The breakpoint mode. Always `explicit`. - - `:image_too_large` + - `:explicit` - - `:image_too_small` +### Beta Response Input Image Content - - `:image_parse_error` +- `class BetaResponseInputImageContent` - - `:image_content_policy_violation` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `:invalid_image_mode` + - `type: :input_image` - - `:image_file_too_large` + The type of the input item. Always `input_image`. - - `:unsupported_image_media_type` + - `:input_image` - - `:empty_image_file` + - `detail: :low | :high | :auto | :original` - - `:failed_to_download_image` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:image_file_not_found` + - `:low` - - `message: String` + - `:high` - A human-readable description of the error. + - `:auto` - - `incomplete_details: IncompleteDetails{ reason}` + - `:original` - Details about why the response is incomplete. + - `file_id: String` - - `reason: :max_output_tokens | :content_filter` + The ID of the file to be sent to the model. - The reason why the response is incomplete. + - `image_url: String` - - `:max_output_tokens` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `:content_filter` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `instructions: String | Array[BetaResponseInputItem]` + Marks the exact end of a reusable 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 system (or developer) message inserted into the model's context. + - `mode: :explicit` - 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 breakpoint mode. Always `explicit`. - - `String = String` + - `:explicit` - A text input to the model, equivalent to a text input with the - `developer` role. +### Beta Response Input Item - - `InputItemList = Array[BetaResponseInputItem]` +- `BetaResponseInputItem = BetaEasyInputMessage | Message{ content, role, agent, 2 more} | BetaResponseOutputMessage | 32 more` - A list of one or many input items to the model, containing - different content types. + 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. - `class BetaEasyInputMessage` @@ -81080,7 +91962,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :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 @@ -81088,6 +91970,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -81327,7 +92211,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -81335,6 +92219,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -82507,7 +93393,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -82517,7 +93403,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -82564,7 +93454,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -82574,7 +93464,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -84574,401 +95468,1412 @@ puts(beta_compacted_response) The name of the custom tool being called. - - `type: :custom_tool_call` + - `type: :custom_tool_call` + + The type of the custom tool call. Always `custom_tool_call`. + + - `:custom_tool_call` + + - `id: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + +### Beta Response Input Message Content List + +- `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` + +### Beta Response Input Message Item + +- `class BetaResponseInputMessageItem` + + - `id: String` + + The unique ID of the message input. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + +### Beta Response Input Text + +- `class BetaResponseInputText` + + 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: PromptCacheBreakpoint{ 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` + +### Beta Response Input Text Content + +- `class BetaResponseInputTextContent` + + 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: PromptCacheBreakpoint{ 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` + +### Beta Response Item + +- `BetaResponseItem = BetaResponseInputMessageItem | BetaResponseOutputMessage | BetaResponseFileSearchToolCall | 29 more` + + Content item used to generate a response. + + - `class BetaResponseInputMessageItem` + + - `id: String` + + The unique ID of the message input. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + 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. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + 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: Integer` + + 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` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `: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: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + 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 | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :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` + + - `class BetaResponseFileSearchToolCall` + + 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[String]` + + The queries used to search for files. + + - `status: :in_progress | :searching | :completed | 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. 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 = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `file_id: String` + + The unique ID of the file. + + - `filename: String` + + The name of the file. + + - `score: Float` + + The relevance score of the file - a value between 0 and 1. + + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + 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[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :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: BetaComputerAction` + + A click action. + + - `class Click` + + A click action. + + - `button: :left | :right | :wheel | 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: Integer` + + The x-coordinate where the click occurred. + + - `y_: Integer` + + The y-coordinate where the click occurred. + + - `keys: Array[String]` + + The keys being held while clicking. + + - `class DoubleClick` + + A double click action. + + - `keys: Array[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: Integer` + + The x-coordinate where the double click occurred. - The type of the custom tool call. Always `custom_tool_call`. + - `y_: Integer` - - `:custom_tool_call` + The y-coordinate where the double click occurred. - - `id: String` + - `class Drag` - The unique ID of the custom tool call in the OpenAI platform. + A drag action. - - `agent: Agent{ agent_name}` + - `path: Array[Path{ x, y_}]` - The agent that produced this item. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `agent_name: String` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The canonical name of the agent that produced this item. + - `x: Integer` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The x-coordinate. - The execution context that produced this tool call. + - `y_: Integer` - - `class Direct` + The y-coordinate. - - `type: :direct` + - `type: :drag` - - `:direct` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `class Program` + - `:drag` - - `caller_id: String` + - `keys: Array[String]` - The call ID of the program item that produced this tool call. + The keys being held while dragging the mouse. - - `type: :program` + - `class Keypress` - - `:program` + A collection of keypresses the model would like to perform. - - `namespace: String` + - `keys: Array[String]` - The namespace of the custom tool being called. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `class CompactionTrigger` + - `type: :keypress` - Compacts the current context. Must be the final input item. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: :compaction_trigger` + - `:keypress` - The type of the item. Always `compaction_trigger`. + - `class Move` - - `:compaction_trigger` + A mouse move action. - - `agent: Agent{ 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: Integer` - - `class ItemReference` + The x-coordinate to move to. - An internal identifier for an item to reference. + - `y_: Integer` - - `id: String` + The y-coordinate to move to. - The ID of the item to reference. + - `keys: Array[String]` - - `agent: Agent{ agent_name}` + The keys being held while moving the mouse. - The agent that produced this item. + - `class Screenshot` - - `agent_name: String` + A screenshot action. - The canonical name of the agent that produced this item. + - `type: :screenshot` - - `type: :item_reference` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The type of item to reference. Always `item_reference`. + - `:screenshot` - - `:item_reference` + - `class Scroll` - - `class Program` + A scroll action. - - `id: String` + - `scroll_x: Integer` - The unique ID of this program item. + The horizontal scroll distance. - - `call_id: String` + - `scroll_y: Integer` - The stable call ID of the program item. + The vertical scroll distance. - - `code: String` + - `type: :scroll` - The JavaScript source executed by programmatic tool calling. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `fingerprint: String` + - `:scroll` - Opaque program replay fingerprint that must be round-tripped. + - `x: Integer` - - `type: :program` + The x-coordinate where the scroll occurred. - The item type. Always `program`. + - `y_: Integer` - - `:program` + The y-coordinate where the scroll occurred. - - `agent: Agent{ agent_name}` + - `keys: Array[String]` - The agent that produced this item. + The keys being held while scrolling. - - `agent_name: String` + - `class Type` - The canonical name of the agent that produced this item. + An action to type in text. - - `class ProgramOutput` + - `text: String` - - `id: String` + The text to type. - The unique ID of this program output item. + - `type: :type` - - `call_id: String` + Specifies the event type. For a type action, this property is always set to `type`. - The call ID of the program item. + - `:type` - - `result: String` + - `class Wait` - The result produced by the program item. + A wait action. - - `status: :completed | :incomplete` + - `type: :wait` - The terminal status of the program output. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `:completed` + - `:wait` - - `:incomplete` + - `actions: BetaComputerActionList` - - `type: :program_output` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The item type. Always `program_output`. + - `class Click` - - `:program_output` + A click action. - - `agent: Agent{ agent_name}` + - `class DoubleClick` - The agent that produced this item. + A double click action. - - `agent_name: String` + - `class Drag` - The canonical name of the agent that produced this item. + A drag action. - - `metadata: Hash[Symbol, String]` + - `class Keypress` - Set of 16 key-value pairs that can be attached to an object. 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 collection of keypresses the model would like to perform. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class Move` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + A mouse move action. - 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. + - `class Screenshot` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + A screenshot action. - 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. + - `class Scroll` - - `:"gpt-5.6-sol"` + A scroll action. - - `:"gpt-5.6-terra"` + - `class Type` - - `:"gpt-5.6-luna"` + An action to type in text. - - `:"gpt-5.4"` + - `class Wait` - - `:"gpt-5.4-mini"` + A wait action. - - `:"gpt-5.4-nano"` + - `agent: Agent{ agent_name}` - - `:"gpt-5.4-mini-2026-03-17"` + The agent that produced this item. - - `:"gpt-5.4-nano-2026-03-17"` + - `agent_name: String` - - `:"gpt-5.3-chat-latest"` + The canonical name of the agent that produced this item. - - `:"gpt-5.2"` + - `class BetaResponseComputerToolCallOutputItem` - - `:"gpt-5.2-2025-12-11"` + - `id: String` - - `:"gpt-5.2-chat-latest"` + The unique ID of the computer call tool output. - - `:"gpt-5.2-pro"` + - `call_id: String` - - `:"gpt-5.2-pro-2025-12-11"` + The ID of the computer tool call that produced the output. - - `:"gpt-5.1"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `:"gpt-5.1-2025-11-13"` + A computer screenshot image used with the computer use tool. - - `:"gpt-5.1-codex"` + - `type: :computer_screenshot` - - `:"gpt-5.1-mini"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:"gpt-5.1-chat-latest"` + - `:computer_screenshot` - - `:"gpt-5"` + - `file_id: String` - - `:"gpt-5-mini"` + The identifier of an uploaded file that contains the screenshot. - - `:"gpt-5-nano"` + - `image_url: String` - - `:"gpt-5-2025-08-07"` + The URL of the screenshot image. - - `:"gpt-5-mini-2025-08-07"` + - `status: :completed | :incomplete | :failed | :in_progress` - - `:"gpt-5-nano-2025-08-07"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `:"gpt-5-chat-latest"` + - `:completed` - - `:"gpt-4.1"` + - `:incomplete` - - `:"gpt-4.1-mini"` + - `:failed` - - `:"gpt-4.1-nano"` + - `:in_progress` - - `:"gpt-4.1-2025-04-14"` + - `type: :computer_call_output` - - `:"gpt-4.1-mini-2025-04-14"` + The type of the computer tool call output. Always `computer_call_output`. - - `:"gpt-4.1-nano-2025-04-14"` + - `:computer_call_output` - - `:"o4-mini"` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:"o4-mini-2025-04-16"` + The safety checks reported by the API that have been acknowledged by the + developer. - - `:o3` + - `id: String` - - `:"o3-2025-04-16"` + The ID of the pending safety check. - - `:"o3-mini"` + - `code: String` - - `:"o3-mini-2025-01-31"` + The type of the pending safety check. - - `:o1` + - `message: String` - - `:"o1-2024-12-17"` + Details about the pending safety check. - - `:"o1-preview"` + - `agent: Agent{ agent_name}` - - `:"o1-preview-2024-09-12"` + The agent that produced this item. - - `:"o1-mini"` + - `agent_name: String` - - `:"o1-mini-2024-09-12"` + The canonical name of the agent that produced this item. - - `:"gpt-4o"` + - `created_by: String` - - `:"gpt-4o-2024-11-20"` + The identifier of the actor that created the item. - - `:"gpt-4o-2024-08-06"` + - `class BetaResponseFunctionWebSearch` - - `:"gpt-4o-2024-05-13"` + 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-4o-audio-preview"` + - `id: String` - - `:"gpt-4o-audio-preview-2024-10-01"` + The unique ID of the web search tool call. - - `:"gpt-4o-audio-preview-2024-12-17"` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `:"gpt-4o-audio-preview-2025-06-03"` + 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-4o-mini-audio-preview"` + - `class Search` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + Action type "search" - Performs a web search query. - - `:"gpt-4o-search-preview"` + - `type: :search` - - `:"gpt-4o-mini-search-preview"` + The action type. - - `:"gpt-4o-search-preview-2025-03-11"` + - `:search` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `queries: Array[String]` - - `:"chatgpt-4o-latest"` + The search queries. - - `:"codex-mini-latest"` + - `query: String` - - `:"gpt-4o-mini"` + The search query. - - `:"gpt-4o-mini-2024-07-18"` + - `sources: Array[Source{ type, url}]` - - `:"gpt-4-turbo"` + The sources used in the search. - - `:"gpt-4-turbo-2024-04-09"` + - `type: :url` - - `:"gpt-4-0125-preview"` + The type of source. Always `url`. - - `:"gpt-4-turbo-preview"` + - `:url` - - `:"gpt-4-1106-preview"` + - `url: String` - - `:"gpt-4-vision-preview"` + The URL of the source. - - `:"gpt-4"` + - `class OpenPage` - - `:"gpt-4-0314"` + Action type "open_page" - Opens a specific URL from search results. - - `:"gpt-4-0613"` + - `type: :open_page` - - `:"gpt-4-32k"` + The action type. - - `:"gpt-4-32k-0314"` + - `:open_page` - - `:"gpt-4-32k-0613"` + - `url: String` - - `:"gpt-3.5-turbo"` + The URL opened by the model. - - `:"gpt-3.5-turbo-16k"` + - `class FindInPage` - - `:"gpt-3.5-turbo-0301"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `:"gpt-3.5-turbo-0613"` + - `pattern: String` - - `:"gpt-3.5-turbo-1106"` + The pattern or text to search for within the page. - - `:"gpt-3.5-turbo-0125"` + - `type: :find_in_page` - - `:"gpt-3.5-turbo-16k-0613"` + The action type. - - `:"o1-pro"` + - `:find_in_page` - - `:"o1-pro-2025-03-19"` + - `url: String` - - `:"o3-pro"` + The URL of the page searched for the pattern. - - `:"o3-pro-2025-06-10"` + - `status: :in_progress | :searching | :completed | :failed` - - `:"o3-deep-research"` + The status of the web search tool call. - - `:"o3-deep-research-2025-06-26"` + - `:in_progress` - - `:"o4-mini-deep-research"` + - `:searching` - - `:"o4-mini-deep-research-2025-06-26"` + - `:completed` - - `:"computer-use-preview"` + - `:failed` - - `:"computer-use-preview-2025-03-11"` + - `type: :web_search_call` - - `:"gpt-5-codex"` + The type of the web search tool call. Always `web_search_call`. - - `:"gpt-5-pro"` + - `:web_search_call` - - `:"gpt-5-pro-2025-10-06"` + - `agent: Agent{ agent_name}` - - `:"gpt-5.1-codex-max"` + The agent that produced this item. - - `String = String` + - `agent_name: String` - - `object: :response` + The canonical name of the agent that produced this item. - The object type of this resource - always set to `response`. + - `class BetaResponseFunctionToolCallItem` - - `:response` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `output: Array[BetaResponseOutputItem]` + - `id: String` - An array of content items generated by the model. + The unique ID of the function tool call. - - 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. + - `status: :in_progress | :completed | :incomplete` - - `class BetaResponseOutputMessage` + 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` - - `class BetaResponseFileSearchToolCall` + - `:completed` - 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. + - `:incomplete` - - `class BetaResponseFunctionToolCall` + - `created_by: String` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The identifier of the actor that created the item. - `class BetaResponseFunctionToolCallOutputItem` @@ -85304,944 +97209,1338 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch` + - `class BetaResponseToolSearchCall` - 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` - - `class BetaResponseComputerToolCall` + The unique ID of the tool search call item. - 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. + - `arguments: untyped` - - `class BetaResponseComputerToolCallOutputItem` + Arguments used for the tool search call. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` - `id: String` - The unique ID of the computer call tool output. + The unique ID of the tool search output item. - `call_id: String` - The ID of the computer tool call that produced the output. + The unique ID of the tool search call generated by the model. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `execution: :server | :client` - A computer screenshot image used with the computer use tool. + Whether tool search was executed by the server or by the client. - - `status: :completed | :incomplete | :failed | :in_progress` + - `:server` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output item that was recorded. + + - `:in_progress` - `:completed` - `:incomplete` - - `:failed` + - `tools: Array[BetaTool]` - - `:in_progress` + The loaded tool definitions returned by tool search. - - `type: :computer_call_output` + - `class BetaFunctionTool` - The type of the computer tool call output. Always `computer_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). - - `:computer_call_output` + - `name: String` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + The name of the function to call. - The safety checks reported by the API that have been acknowledged by the - developer. + - `parameters: Hash[Symbol, untyped]` - - `id: String` + A JSON schema object describing the parameters of the function. - The ID of the pending safety check. + - `strict: bool` - - `code: String` + Whether strict parameter validation is enforced for this function tool. - The type of the pending safety check. + - `type: :function` - - `message: String` + The type of the function tool. Always `function`. - Details about the pending safety check. + - `:function` - - `agent: Agent{ agent_name}` + - `allowed_callers: Array[:direct | :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` - - `created_by: String` + - `defer_loading: bool` - The identifier of the actor that created the item. + Whether this function is deferred and loaded via tool search. - - `class BetaResponseReasoningItem` + - `description: 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). + A description of the function. Used by the model to determine whether or not to call the function. - - `class Program` + - `output_schema: Hash[Symbol, untyped]` - - `id: String` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The unique ID of the program item. + - `class BetaFileSearchTool` - - `call_id: String` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The stable call ID of the program item. + - `type: :file_search` - - `code: String` + The type of the file search tool. Always `file_search`. - The JavaScript source executed by programmatic tool calling. + - `:file_search` - - `fingerprint: String` + - `vector_store_ids: Array[String]` - Opaque program replay fingerprint that must be round-tripped. + The IDs of the vector stores to search. - - `type: :program` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - The type of the item. Always `program`. + A filter to apply. - - `:program` + - `class ComparisonFilter` - - `agent: Agent{ agent_name}` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The agent that produced this item. + - `key: String` - - `agent_name: String` + The key to compare against the value. - The canonical name of the agent that produced this item. + - `type: :eq | :ne | :gt | 5 more` - - `class ProgramOutput` + 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 program output item. + - `:eq` - - `call_id: String` + - `:ne` - The call ID of the program item. + - `:gt` - - `result: String` + - `:gte` - The result produced by the program item. + - `:lt` - - `status: :completed | :incomplete` + - `:lte` - The terminal status of the program output item. + - `:in` - - `:completed` + - `:nin` - - `:incomplete` + - `value: String | Float | bool | Array[String | Float]` - - `type: :program_output` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the item. Always `program_output`. + - `String = String` - - `:program_output` + - `Float = Float` - - `agent: Agent{ agent_name}` + - `UnionMember2 = bool` - The agent that produced this item. + - `UnionMember3 = Array[String | Float]` - - `agent_name: String` + - `String = String` - The canonical name of the agent that produced this item. + - `Float = Float` - - `class BetaResponseToolSearchCall` + - `class CompoundFilter` - - `id: String` + Combine multiple filters using `and` or `or`. - The unique ID of the tool search call item. + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `arguments: untyped` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Arguments used for the tool search call. + - `class ComparisonFilter` - - `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 tool search call generated by the model. + - `key: String` - - `execution: :server | :client` + The key to compare against the value. - Whether tool search was executed by the server or by the client. + - `type: :eq | :ne | :gt | 5 more` - - `:server` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:client` + - `eq`: equals + - `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 | :completed | :incomplete` + - `:eq` - The status of the tool search call item that was recorded. + - `:ne` - - `:in_progress` + - `:gt` - - `:completed` + - `:gte` - - `:incomplete` + - `:lt` - - `type: :tool_search_call` + - `:lte` - The type of the item. Always `tool_search_call`. + - `:in` - - `:tool_search_call` + - `:nin` - - `agent: Agent{ agent_name}` + - `value: String | Float | bool | Array[String | Float]` - The agent that produced this item. + The value to compare against the attribute key; supports string, number, or boolean types. - - `agent_name: String` + - `String = String` - The canonical name of the agent that produced this item. + - `Float = Float` - - `created_by: String` + - `UnionMember2 = bool` - The identifier of the actor that created the item. + - `UnionMember3 = Array[String | Float]` - - `class BetaResponseToolSearchOutputItem` + - `String = String` - - `id: String` + - `Float = Float` - The unique ID of the tool search output item. + - `UnionMember1 = untyped` - - `call_id: String` + - `type: :and | :or` - The unique ID of the tool search call generated by the model. + Type of operation: `and` or `or`. - - `execution: :server | :client` + - `:and` - Whether tool search was executed by the server or by the client. + - `:or` - - `:server` + - `max_num_results: Integer` - - `:client` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `status: :in_progress | :completed | :incomplete` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The status of the tool search output item that was recorded. + Ranking options for search. - - `:in_progress` + - `hybrid_search: HybridSearch{ 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. - - `:incomplete` + - `embedding_weight: Float` - - `tools: Array[BetaTool]` + The weight of the embedding in the reciprocal ranking fusion. - The loaded tool definitions returned by tool search. + - `text_weight: Float` - - `class BetaFunctionTool` + The weight of the text in the reciprocal ranking fusion. - 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). + - `ranker: :auto | :"default-2024-11-15"` + + The ranker to use for the file search. + + - `:auto` + + - `:"default-2024-11-15"` + + - `score_threshold: Float` + + 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. + + - `class BetaComputerTool` + + 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` + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: Integer` + + The height of the computer display. + + - `display_width: Integer` + + The width of the computer display. + + - `environment: :windows | :mac | :linux | 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` + + - `class BetaWebSearchTool` + + 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 | :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: Filters{ allowed_domains}` + + Filters for the search. + + - `allowed_domains: Array[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: :low | :medium | :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: UserLocation{ city, country, region, 2 more}` + + The approximate location of the user. + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `class Mcp` + + 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: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = Array[String]` + + A string array of allowed tool names + + - `class McpToolFilter` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `authorization: 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: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 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: bool` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Hash[Symbol, String]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter` + + 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: Always{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `never: Never{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-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: Array[String]` + + List of allowed tool names. + + - `McpToolApprovalSetting = :always | :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: String` + + Optional description of the MCP server, used to provide more context. + + - `server_url: String` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_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. + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: String | CodeInterpreterToolAuto{ 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 = String` + + The container ID. + + - `class CodeInterpreterToolAuto` + + 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: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the code interpreter container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `type: :disabled` + + Disable outbound network access. Always `disabled`. + + - `:disabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `allowed_domains: Array[String]` + + A list of allowed domains when type is `allowlist`. + + - `type: :allowlist` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `:allowlist` - - `class BetaFileSearchTool` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - 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 domain-scoped secrets for allowlisted domains. - - `class BetaComputerTool` + - `domain: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The domain associated with the secret. - - `class BetaComputerUsePreviewTool` + - `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 secret to inject for the domain. - - `class BetaWebSearchTool` + - `value: 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 secret value to inject for the domain. - - `class Mcp` + - `type: :code_interpreter` - 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 type of the code interpreter tool. Always `code_interpreter`. - - `class CodeInterpreter` + - `:code_interpreter` - A tool that runs Python code to help generate a response to a prompt. + - `allowed_callers: Array[:direct | :programmatic]` - - `class ProgrammaticToolCalling` + The tool invocation context(s). - - `class ImageGeneration` + - `:direct` - A tool that generates images using the GPT image models. + - `:programmatic` - - `class LocalShell` + - `class ProgrammaticToolCalling` - A tool that allows the model to execute shell commands in a local environment. + - `type: :programmatic_tool_calling` - - `class BetaFunctionShellTool` + The type of the tool. Always `programmatic_tool_calling`. - A tool that allows the model to execute shell commands. + - `:programmatic_tool_calling` - - `class BetaCustomTool` + - `class ImageGeneration` - 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 tool that generates images using the GPT image models. - - `class BetaNamespaceTool` + - `type: :image_generation` - Groups function/custom tools under a shared namespace. + The type of the image generation tool. Always `image_generation`. - - `class BetaToolSearchTool` + - `:image_generation` - Hosted or BYOT tool search configuration for deferred tools. + - `action: :generate | :edit | :auto` - - `class BetaWebSearchPreviewTool` + Whether to generate a new image or edit an existing image. Default: `auto`. - 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). + - `:generate` - - `class BetaApplyPatchTool` + - `:edit` - Allows the assistant to create, delete, or update files using unified diffs. + - `:auto` - - `type: :tool_search_output` + - `background: :transparent | :opaque | :auto` - The type of the item. Always `tool_search_output`. + 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. - - `:tool_search_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. - - `agent: Agent{ agent_name}` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The agent that produced this item. + - `:transparent` - - `agent_name: String` + - `:opaque` - The canonical name of the agent that produced this item. + - `:auto` - - `created_by: String` + - `input_fidelity: :high | :low` - The identifier of the actor that created the 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`. - - `class AdditionalTools` + - `:high` - - `id: String` + - `:low` - The unique ID of the additional tools item. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `role: :unknown | :user | :assistant | 5 more` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The role that provided the additional tools. + - `file_id: String` - - `:unknown` + File ID for the mask image. - - `:user` + - `image_url: String` - - `:assistant` + Base64-encoded mask image. - - `:system` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:critic` + The image generation model to use. Default: `gpt-image-1`. - - `:discriminator` + - `String = String` - - `:developer` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:tool` + The image generation model to use. Default: `gpt-image-1`. - - `tools: Array[BetaTool]` + - `:"gpt-image-1"` - The additional tool definitions made available at this item. + - `:"gpt-image-1-mini"` - - `class BetaFunctionTool` + - `:"gpt-image-2"` - 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-image-2-2026-04-21"` - - `class BetaFileSearchTool` + - `:"gpt-image-1.5"` - 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). + - `:"chatgpt-image-latest"` - - `class BetaComputerTool` + - `moderation: :auto | :low` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Moderation level for the generated image. Default: `auto`. - - `class BetaComputerUsePreviewTool` + - `:auto` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:low` - - `class BetaWebSearchTool` + - `output_compression: Integer` - 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). + Compression level for the output image. Default: 100. - - `class Mcp` + - `output_format: :png | :webp | :jpeg` - 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 output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `class CodeInterpreter` + - `:png` - A tool that runs Python code to help generate a response to a prompt. + - `:webp` - - `class ProgrammaticToolCalling` + - `:jpeg` - - `class ImageGeneration` + - `partial_images: Integer` - A tool that generates images using the GPT image models. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `class LocalShell` + - `quality: :low | :medium | :high | :auto` - A tool that allows the model to execute shell commands in a local environment. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `class BetaFunctionShellTool` + - `:low` - A tool that allows the model to execute shell commands. + - `:medium` - - `class BetaCustomTool` + - `:high` - 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) + - `:auto` - - `class BetaNamespaceTool` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - Groups function/custom tools under a shared namespace. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class BetaToolSearchTool` + - `String = String` - Hosted or BYOT tool search configuration for deferred tools. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `class BetaWebSearchPreviewTool` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - 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). + - `:"1024x1024"` - - `class BetaApplyPatchTool` + - `:"1024x1536"` - Allows the assistant to create, delete, or update files using unified diffs. + - `:"1536x1024"` - - `type: :additional_tools` + - `:auto` - The type of the item. Always `additional_tools`. + - `class LocalShell` - - `:additional_tools` + A tool that allows the model to execute shell commands in a local environment. - - `agent: Agent{ agent_name}` + - `type: :local_shell` - The agent that produced this item. + The type of the local shell tool. Always `local_shell`. - - `agent_name: String` + - `:local_shell` - The canonical name of the agent that produced this item. + - `class BetaFunctionShellTool` - - `class BetaResponseCompactionItem` + A tool that allows the model to execute shell commands. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `type: :shell` - - `id: String` + The type of the shell tool. Always `shell`. - The unique ID of the compaction item. + - `:shell` - - `encrypted_content: String` + - `allowed_callers: Array[:direct | :programmatic]` - The encrypted content that was produced by compaction. + The tool invocation context(s). - - `type: :compaction` + - `:direct` - The type of the item. Always `compaction`. + - `:programmatic` - - `:compaction` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `agent: Agent{ agent_name}` + - `class BetaContainerAuto` - The agent that produced this item. + - `type: :container_auto` - - `agent_name: String` + Automatically creates a container for this request - The canonical name of the agent that produced this item. + - `:container_auto` - - `created_by: String` + - `file_ids: Array[String]` - The identifier of the actor that created the item. + An optional list of uploaded files to make available to your code. - - `class ImageGenerationCall` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - An image generation request made by the model. + The memory limit for the container. - - `id: String` + - `:"1g"` - The unique ID of the image generation call. + - `:"4g"` - - `result: String` + - `:"16g"` - The generated image encoded in base64. + - `:"64g"` - - `status: :in_progress | :completed | :generating | :failed` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The status of the image generation call. + Network access policy for the container. - - `:in_progress` + - `class BetaContainerNetworkPolicyDisabled` - - `:completed` + - `class BetaContainerNetworkPolicyAllowlist` - - `:generating` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `:failed` + An optional list of skills referenced by id or inline data. - - `type: :image_generation_call` + - `class BetaSkillReference` - The type of the image generation call. Always `image_generation_call`. + - `skill_id: String` - - `:image_generation_call` + The ID of the referenced skill. - - `agent: Agent{ agent_name}` + - `type: :skill_reference` - The agent that produced this item. + References a skill created with the /v1/skills endpoint. - - `agent_name: String` + - `:skill_reference` - The canonical name of the agent that produced this item. + - `version: String` - - `class BetaResponseCodeInterpreterToolCall` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A tool call to run code. + - `class BetaInlineSkill` - - `class LocalShellCall` + - `description: String` - A tool call to run a command on the local shell. + The description of the skill. - - `id: String` + - `name: String` - The unique ID of the local shell call. + The name of the skill. - - `action: Action{ command, env, type, 3 more}` + - `source: BetaInlineSkillSource` - Execute a shell command on the server. + Inline skill payload - - `command: Array[String]` + - `data: String` - The command to run. + Base64-encoded skill zip bundle. - - `env: Hash[Symbol, String]` + - `media_type: :"application/zip"` - Environment variables to set for the command. + The media type of the inline skill payload. Must be `application/zip`. - - `type: :exec` + - `:"application/zip"` - The type of the local shell action. Always `exec`. + - `type: :base64` - - `:exec` + The type of the inline skill source. Must be `base64`. - - `timeout_ms: Integer` + - `:base64` - Optional timeout in milliseconds for the command. + - `type: :inline` - - `user: String` + Defines an inline skill for this request. - Optional user to run the command as. + - `:inline` - - `working_directory: String` + - `class BetaLocalEnvironment` - Optional working directory to run the command in. + - `type: :local` - - `call_id: String` + Use a local computer environment. - The unique ID of the local shell tool call generated by the model. + - `:local` - - `status: :in_progress | :completed | :incomplete` + - `skills: Array[BetaLocalSkill]` - The status of the local shell call. + An optional list of skills. - - `:in_progress` + - `description: String` - - `:completed` + The description of the skill. - - `:incomplete` + - `name: String` - - `type: :local_shell_call` + The name of the skill. - The type of the local shell call. Always `local_shell_call`. + - `path: String` - - `:local_shell_call` + The path to the directory containing the skill. - - `agent: Agent{ agent_name}` + - `class BetaContainerReference` - The agent that produced this item. + - `container_id: String` - - `agent_name: String` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: :container_reference` - - `class LocalShellCallOutput` + References a container created with the /v1/containers endpoint - The output of a local shell tool call. + - `:container_reference` - - `id: String` + - `class BetaCustomTool` - The unique ID of the local shell tool call generated by the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `output: String` + - `name: String` - A JSON string of the output of the local shell tool call. + The name of the custom tool, used to identify it in tool calls. - - `type: :local_shell_call_output` + - `type: :custom` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the custom tool. Always `custom`. - - `:local_shell_call_output` + - `:custom` - - `agent: Agent{ agent_name}` + - `allowed_callers: Array[:direct | :programmatic]` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: String` + - `:direct` - The canonical name of the agent that produced this item. + - `:programmatic` - - `status: :in_progress | :completed | :incomplete` + - `defer_loading: bool` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Whether this tool should be deferred and discovered via tool search. - - `:in_progress` + - `description: String` - - `:completed` + Optional description of the custom tool, used to provide more context. - - `:incomplete` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `class BetaResponseFunctionShellToolCall` + The input format for the custom tool. Default is unconstrained text. - A tool call that executes one or more shell commands in a managed environment. + - `class Text` - - `id: String` + Unconstrained free-form text. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: :text` - - `action: Action{ commands, max_output_length, timeout_ms}` + Unconstrained text format. Always `text`. - The shell commands and limits that describe how to run the tool call. + - `:text` - - `commands: Array[String]` + - `class Grammar` - - `max_output_length: Integer` + A grammar defined by the user. - Optional maximum number of characters to return from each command. + - `definition: String` - - `timeout_ms: Integer` + The grammar definition. - Optional timeout in milliseconds for the commands. + - `syntax: :lark | :regex` - - `call_id: String` + The syntax of the grammar definition. One of `lark` or `regex`. - The unique ID of the shell tool call generated by the model. + - `:lark` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `:regex` - Represents the use of a local environment to perform shell actions. + - `type: :grammar` - - `class BetaResponseLocalEnvironment` + Grammar format. Always `grammar`. - Represents the use of a local environment to perform shell actions. + - `:grammar` - - `type: :local` + - `class BetaNamespaceTool` - The environment type. Always `local`. + Groups function/custom tools under a shared namespace. - - `:local` + - `description: String` - - `class BetaResponseContainerReference` + A description of the namespace shown to the model. - Represents a container created with /v1/containers. + - `name: String` - - `container_id: String` + The namespace name used in tool calls (for example, `crm`). - - `type: :container_reference` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - The environment type. Always `container_reference`. + The function/custom tools available inside this namespace. - - `:container_reference` + - `class Function` - - `status: :in_progress | :completed | :incomplete` + - `name: String` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `type: :function` - - `:in_progress` + - `:function` - - `:completed` + - `allowed_callers: Array[:direct | :programmatic]` - - `:incomplete` + The tool invocation context(s). - - `type: :shell_call` + - `:direct` - The type of the item. Always `shell_call`. + - `:programmatic` - - `:shell_call` + - `defer_loading: bool` - - `agent: Agent{ agent_name}` + Whether this function should be deferred and discovered via tool search. - The agent that produced this item. + - `description: String` - - `agent_name: String` + - `output_schema: Hash[Symbol, untyped]` - 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. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `parameters: untyped` - The execution context that produced this tool call. + - `strict: bool` - - `class 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. - - `type: :direct` + - `class BetaCustomTool` - - `: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) - - `class Program` + - `type: :namespace` - - `caller_id: String` + The type of the tool. Always `namespace`. - The call ID of the program item that produced this tool call. + - `:namespace` - - `type: :program` + - `class BetaToolSearchTool` - - `:program` + Hosted or BYOT tool search configuration for deferred tools. - - `created_by: String` + - `type: :tool_search` - The ID of the entity that created this tool call. + The type of the tool. Always `tool_search`. - - `class BetaResponseFunctionShellToolCallOutput` + - `:tool_search` - The output of a shell tool call that was emitted. + - `description: String` - - `id: String` + Description shown to the model for a client-executed tool search tool. - The unique ID of the shell call output. Populated when this item is returned via API. + - `execution: :server | :client` - - `call_id: String` + Whether tool search is executed by the server or by the client. - The unique ID of the shell tool call generated by the model. + - `:server` - - `max_output_length: Integer` + - `:client` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `parameters: untyped` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + Parameter schema for a client-executed tool search tool. - An array of shell call output contents + - `class BetaWebSearchPreviewTool` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `class Timeout` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Indicates that the shell call exceeded its configured time limit. + - `:web_search_preview` - - `type: :timeout` + - `:web_search_preview_2025_03_11` - The outcome type. Always `timeout`. + - `search_content_types: Array[:text | :image]` - - `:timeout` + - `:text` - - `class Exit` + - `:image` - Indicates that the shell commands finished and returned an exit code. + - `search_context_size: :low | :medium | :high` - - `exit_code: Integer` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Exit code from the shell process. + - `:low` - - `type: :exit` + - `:medium` - The outcome type. Always `exit`. + - `:high` - - `:exit` + - `user_location: UserLocation{ type, city, country, 2 more}` - - `stderr: String` + The user's location. - The standard error output that was captured. + - `type: :approximate` - - `stdout: String` + The type of location approximation. Always `approximate`. - The standard output that was captured. + - `:approximate` - - `created_by: String` + - `city: String` - The identifier of the actor that created the item. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: :in_progress | :completed | :incomplete` + - `country: String` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `:in_progress` + - `region: String` - - `:completed` + Free text input for the region of the user, e.g. `California`. - - `:incomplete` + - `timezone: String` - - `type: :shell_call_output` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the shell call output. Always `shell_call_output`. + - `class BetaApplyPatchTool` - - `:shell_call_output` + Allows the assistant to create, delete, or update files using unified diffs. - - `agent: Agent{ agent_name}` + - `type: :apply_patch` - The agent that produced this item. + The type of the tool. Always `apply_patch`. - - `agent_name: String` + - `:apply_patch` - The canonical name of the agent that produced this item. + - `allowed_callers: Array[:direct | :programmatic]` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The tool invocation context(s). - The execution context that produced this tool call. + - `:direct` - - `class Direct` + - `:programmatic` - - `type: :direct` + - `type: :tool_search_output` - - `:direct` + The type of the item. Always `tool_search_output`. - - `class Program` + - `:tool_search_output` - - `caller_id: String` + - `agent: Agent{ 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: String` The identifier of the actor that created the item. - - `class BetaResponseApplyPatchToolCall` - - A tool call that applies file diffs by creating, deleting, or updating files. + - `class AdditionalTools` - `id: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: String` - - The unique ID of the apply patch tool call generated by the model. + The unique ID of the additional tools item. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `role: :unknown | :user | :assistant | 5 more` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The role that provided the additional tools. - - `class CreateFile` + - `:unknown` - Instruction describing how to create a file via the apply_patch tool. + - `:user` - - `diff: String` + - `:assistant` - Diff to apply. + - `:system` - - `path: String` + - `:critic` - Path of the file to create. + - `:discriminator` - - `type: :create_file` + - `:developer` - Create a new file with the provided diff. + - `:tool` - - `:create_file` + - `tools: Array[BetaTool]` - - `class DeleteFile` + The additional tool definitions made available at this item. - Instruction describing how to delete a file via the apply_patch tool. + - `class BetaFunctionTool` - - `path: String` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Path of the file to delete. + - `class BetaFileSearchTool` - - `type: :delete_file` + 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). - Delete the specified file. + - `class BetaComputerTool` - - `:delete_file` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class UpdateFile` + - `class BetaComputerUsePreviewTool` - Instruction describing how to update a file via the apply_patch tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `diff: String` + - `class BetaWebSearchTool` - Diff to apply. + 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). - - `path: String` + - `class Mcp` - Path of the file to update. + 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: :update_file` + - `class CodeInterpreter` - Update an existing file with the provided diff. + A tool that runs Python code to help generate a response to a prompt. - - `:update_file` + - `class ProgrammaticToolCalling` - - `status: :in_progress | :completed` + - `class ImageGeneration` - The status of the apply patch tool call. One of `in_progress` or `completed`. + A tool that generates images using the GPT image models. - - `:in_progress` + - `class LocalShell` - - `:completed` + A tool that allows the model to execute shell commands in a local environment. - - `type: :apply_patch_call` + - `class BetaFunctionShellTool` - The type of the item. Always `apply_patch_call`. + A tool that allows the model to execute shell commands. - - `:apply_patch_call` + - `class BetaCustomTool` - - `agent: Agent{ 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. + - `class BetaNamespaceTool` - - `agent_name: String` + Groups function/custom tools under a shared namespace. - The canonical name of the agent that produced this item. + - `class BetaToolSearchTool` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Hosted or BYOT tool search configuration for deferred tools. - The execution context that produced this tool call. + - `class BetaWebSearchPreviewTool` - - `class 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). - - `type: :direct` + - `class BetaApplyPatchTool` - - `:direct` + Allows the assistant to create, delete, or update files using unified diffs. - - `class Program` + - `type: :additional_tools` - - `caller_id: String` + The type of the item. Always `additional_tools`. - The call ID of the program item that produced this tool call. + - `:additional_tools` - - `type: :program` + - `agent: Agent{ agent_name}` - - `:program` + The agent that produced this item. - - `created_by: String` + - `agent_name: String` - The ID of the entity that created this tool call. + The canonical name of the agent that produced this item. - - `class BetaResponseApplyPatchToolCallOutput` + - `class BetaResponseReasoningItem` - The output emitted by an apply patch 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). - `id: String` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The unique identifier of the reasoning content. - - `call_id: String` + - `summary: Array[Summary{ text, type}]` - The unique ID of the apply patch tool call generated by the model. + Reasoning summary content. - - `status: :completed | :failed` + - `text: String` - The status of the apply patch tool call output. One of `completed` or `failed`. + A summary of the reasoning output from the model so far. - - `:completed` + - `type: :summary_text` - - `:failed` + The type of the object. Always `summary_text`. - - `type: :apply_patch_call_output` + - `:summary_text` - The type of the item. Always `apply_patch_call_output`. + - `type: :reasoning` - - `:apply_patch_call_output` + The type of the object. Always `reasoning`. + + - `:reasoning` - `agent: Agent{ agent_name}` @@ -86251,59 +98550,59 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. + - `content: Array[Content{ text, type}]` - - `class Direct` + Reasoning text content. - - `type: :direct` + - `text: String` - - `:direct` + The reasoning text from the model. - - `class Program` + - `type: :reasoning_text` - - `caller_id: String` + The type of the reasoning text. Always `reasoning_text`. - The call ID of the program item that produced this tool call. + - `:reasoning_text` - - `type: :program` + - `encrypted_content: String` - - `:program` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `created_by: String` + - `status: :in_progress | :completed | :incomplete` - The ID of the entity that created this tool call output. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `output: String` + - `:in_progress` - Optional textual output returned by the apply patch tool. + - `:completed` - - `class McpCall` + - `:incomplete` - An invocation of a tool on an MCP server. + - `class Program` - `id: String` - The unique ID of the tool call. + The unique ID of the program item. - - `arguments: String` + - `call_id: String` - A JSON string of the arguments passed to the tool. + The stable call ID of the program item. - - `name: String` + - `code: String` - The name of the tool that was run. + The JavaScript source executed by programmatic tool calling. - - `server_label: String` + - `fingerprint: String` - The label of the MCP server running the tool. + Opaque program replay fingerprint that must be round-tripped. - - `type: :mcp_call` + - `type: :program` - The type of the item. Always `mcp_call`. + The type of the item. Always `program`. - - `:mcp_call` + - `:program` - `agent: Agent{ agent_name}` @@ -86313,70 +98612,59 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `approval_request_id: String` + - `class ProgramOutput` - 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: String` + The unique ID of the program output item. - The error from the tool call, if any. + - `call_id: String` - - `output: String` + The call ID of the program item. - The output from the tool call. + - `result: String` - - `status: :in_progress | :completed | :incomplete | 2 more` + The result produced by the program item. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `status: :completed | :incomplete` - - `:in_progress` + The terminal status of the program output item. - `:completed` - `:incomplete` - - `:calling` - - - `:failed` - - - `class McpListTools` - - A list of tools available on an MCP server. - - - `id: String` - - The unique ID of the list. + - `type: :program_output` - - `server_label: String` + The type of the item. Always `program_output`. - The label of the MCP server. + - `:program_output` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `agent: Agent{ agent_name}` - The tools available on the server. + The agent that produced this item. - - `input_schema: untyped` + - `agent_name: String` - The JSON schema describing the tool's input. + The canonical name of the agent that produced this item. - - `name: String` + - `class BetaResponseCompactionItem` - The name of the tool. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `annotations: untyped` + - `id: String` - Additional annotations about the tool. + The unique ID of the compaction item. - - `description: String` + - `encrypted_content: String` - The description of the tool. + The encrypted content that was produced by compaction. - - `type: :mcp_list_tools` + - `type: :compaction` - The type of the item. Always `mcp_list_tools`. + The type of the item. Always `compaction`. - - `:mcp_list_tools` + - `:compaction` - `agent: Agent{ agent_name}` @@ -86386,35 +98674,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `error: String` + - `created_by: String` - Error message if the server could not list tools. + The identifier of the actor that created the item. - - `class McpApprovalRequest` + - `class ImageGenerationCall` - A request for human approval of a tool invocation. + An image generation request made by the model. - `id: String` - The unique ID of the approval request. + The unique ID of the image generation call. - - `arguments: String` + - `result: String` - A JSON string of arguments for the tool. + The generated image encoded in base64. - - `name: String` + - `status: :in_progress | :completed | :generating | :failed` - The name of the tool to run. + The status of the image generation call. - - `server_label: String` + - `:in_progress` - The label of the MCP server making the request. + - `:completed` - - `type: :mcp_approval_request` + - `:generating` - The type of the item. Always `mcp_approval_request`. + - `:failed` - - `:mcp_approval_request` + - `type: :image_generation_call` + + The type of the image generation call. Always `image_generation_call`. + + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -86424,56 +98716,58 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse` + - `class BetaResponseCodeInterpreterToolCall` - A response to an MCP approval request. + A tool call to run code. - `id: String` - The unique ID of the approval response + The unique ID of the code interpreter tool call. - - `approval_request_id: String` + - `code: String` - The ID of the approval request being answered. + The code to run, or null if not available. - - `approve: bool` + - `container_id: String` - Whether the request was approved. + The ID of the container used to run the code. - - `type: :mcp_approval_response` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - The type of the item. Always `mcp_approval_response`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `:mcp_approval_response` + - `class Logs` - - `agent: Agent{ agent_name}` + The logs output from the code interpreter. - The agent that produced this item. + - `logs: String` - - `agent_name: String` + The logs output from the code interpreter. - The canonical name of the agent that produced this item. + - `type: :logs` - - `reason: String` + The type of the output. Always `logs`. - Optional reason for the decision. + - `:logs` - - `class BetaResponseCustomToolCall` + - `class Image` - A call to a custom tool created by the model. + The image output from the code interpreter. - - `class BetaResponseCustomToolCallOutputItem` + - `type: :image` - The output of a custom tool call from your code, being sent back to the model. + The type of the output. Always `image`. - - `id: String` + - `:image` - The unique ID of the custom tool call output item. + - `url: String` - - `status: :in_progress | :completed | :incomplete` + The URL of the image output from the code interpreter. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `:in_progress` @@ -86481,1145 +98775,1034 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` - - The identifier of the actor that created the item. - - - `parallel_tool_calls: bool` + - `:interpreting` - Whether to allow the model to run tool calls in parallel. + - `:failed` - - `temperature: Float` + - `type: :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. - We generally recommend altering this or `top_p` but not both. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `:code_interpreter_call` - 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. + - `agent: Agent{ agent_name}` - - `BetaToolChoiceOptions = :none | :auto | :required` + The agent that produced this item. - Controls which (if any) tool is called by the model. + - `agent_name: String` - `none` means the model will not call any tool and instead generates a message. + The canonical name of the agent that produced this item. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `class LocalShellCall` - `required` means the model must call one or more tools. + A tool call to run a command on the local shell. - - `:none` + - `id: String` - - `:auto` + The unique ID of the local shell call. - - `:required` + - `action: Action{ command, env, type, 3 more}` - - `class BetaToolChoiceAllowed` + Execute a shell command on the server. - Constrains the tools available to the model to a pre-defined set. + - `command: Array[String]` - - `mode: :auto | :required` + The command to run. - Constrains the tools available to the model to a pre-defined set. + - `env: Hash[Symbol, String]` - `auto` allows the model to pick from among the allowed tools and generate a - message. + Environment variables to set for the command. - `required` requires the model to call one or more of the allowed tools. + - `type: :exec` - - `:auto` + The type of the local shell action. Always `exec`. - - `:required` + - `:exec` - - `tools: Array[Hash[Symbol, untyped]]` + - `timeout_ms: Integer` - A list of tool definitions that the model should be allowed to call. + Optional timeout in milliseconds for the command. - For the Responses API, the list of tool definitions might look like: + - `user: String` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Optional user to run the command as. - - `type: :allowed_tools` + - `working_directory: String` - Allowed tool configuration type. Always `allowed_tools`. + Optional working directory to run the command in. - - `:allowed_tools` + - `call_id: String` - - `class BetaToolChoiceTypes` + The unique ID of the local shell tool call generated by the model. - 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). + - `status: :in_progress | :completed | :incomplete` - - `type: :file_search | :web_search_preview | :computer | 5 more` + The status of the local shell call. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `:in_progress` - Allowed values are: + - `:completed` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `:incomplete` - - `:file_search` + - `type: :local_shell_call` - - `:web_search_preview` + The type of the local shell call. Always `local_shell_call`. - - `:computer` + - `:local_shell_call` - - `:computer_use_preview` + - `agent: Agent{ agent_name}` - - `:computer_use` + The agent that produced this item. - - `:web_search_preview_2025_03_11` + - `agent_name: String` - - `:image_generation` + The canonical name of the agent that produced this item. - - `:code_interpreter` + - `class LocalShellCallOutput` - - `class BetaToolChoiceFunction` + The output of a local shell tool call. - Use this option to force the model to call a specific function. + - `id: String` - - `name: String` + The unique ID of the local shell tool call generated by the model. - The name of the function to call. + - `output: String` - - `type: :function` + A JSON string of the output of the local shell tool call. - For function calling, the type is always `function`. + - `type: :local_shell_call_output` - - `:function` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `class BetaToolChoiceMcp` + - `:local_shell_call_output` - Use this option to force the model to call a specific tool on a remote MCP server. + - `agent: Agent{ 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`. + - `status: :in_progress | :completed | :incomplete` - - `:mcp` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `name: String` + - `:in_progress` - The name of the tool to call on the server. + - `:completed` - - `class BetaToolChoiceCustom` + - `:incomplete` - Use this option to force the model to call a specific custom tool. + - `class BetaResponseFunctionShellToolCall` - - `name: String` + A tool call that executes one or more shell commands in a managed environment. - The name of the custom tool to call. + - `id: String` - - `type: :custom` + The unique ID of the shell tool call. Populated when this item is returned via API. - For custom tool calling, the type is always `custom`. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:custom` + The shell commands and limits that describe how to run the tool call. - - `class BetaSpecificProgrammaticToolCallingParam` + - `commands: Array[String]` - - `type: :programmatic_tool_calling` + - `max_output_length: Integer` - The tool to call. Always `programmatic_tool_calling`. + Optional maximum number of characters to return from each command. - - `:programmatic_tool_calling` + - `timeout_ms: Integer` - - `class BetaToolChoiceApplyPatch` + Optional timeout in milliseconds for the commands. - Forces the model to call the apply_patch tool when executing a tool call. + - `call_id: String` - - `type: :apply_patch` + The unique ID of the shell tool call generated by the model. - The tool to call. Always `apply_patch`. + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:apply_patch` + Represents the use of a local environment to perform shell actions. - - `class BetaToolChoiceShell` + - `class BetaResponseLocalEnvironment` - Forces the model to call the shell tool when a tool call is required. + Represents the use of a local environment to perform shell actions. - - `type: :shell` + - `type: :local` - The tool to call. Always `shell`. + The environment type. Always `local`. - - `:shell` + - `:local` - - `tools: Array[BetaTool]` + - `class BetaResponseContainerReference` - 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. + Represents a container created with /v1/containers. - We support the following categories of tools: + - `container_id: 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. + - `type: :container_reference` - - `class BetaFunctionTool` + The environment type. Always `container_reference`. - 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_reference` - - `class BetaFileSearchTool` + - `status: :in_progress | :completed | :incomplete` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `class BetaComputerTool` + - `: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` - - `class BetaComputerUsePreviewTool` + - `:incomplete` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :shell_call` - - `class BetaWebSearchTool` + The type of the item. Always `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). + - `:shell_call` - - `class Mcp` + - `agent: Agent{ 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. - - `class CodeInterpreter` + - `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. - - `class ProgrammaticToolCalling` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class ImageGeneration` + The execution context that produced this tool call. - A tool that generates images using the GPT image models. + - `class Direct` - - `class LocalShell` + - `type: :direct` - A tool that allows the model to execute shell commands in a local environment. + - `:direct` - - `class BetaFunctionShellTool` + - `class Program` - A tool that allows the model to execute shell commands. + - `caller_id: String` - - `class BetaCustomTool` + The call ID of the program item that produced this tool 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) + - `type: :program` - - `class BetaNamespaceTool` + - `:program` - Groups function/custom tools under a shared namespace. + - `created_by: String` - - `class BetaToolSearchTool` + The ID of the entity that created this tool call. - Hosted or BYOT tool search configuration for deferred tools. + - `class BetaResponseFunctionShellToolCallOutput` - - `class BetaWebSearchPreviewTool` + The output of a shell tool call that was emitted. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `id: String` - - `class BetaApplyPatchTool` + The unique ID of the shell call output. Populated when this item is returned via API. - Allows the assistant to create, delete, or update files using unified diffs. + - `call_id: String` - - `top_p: Float` + The unique ID of the 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. + - `max_output_length: Integer` - We generally recommend altering this or `temperature` but not both. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `background: bool` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + An array of shell call output contents - - `completed_at: Float` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `conversation: Conversation{ id}` + - `class Timeout` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + Indicates that the shell call exceeded its configured time limit. - - `id: String` + - `type: :timeout` - The unique ID of the conversation that this response was associated with. + The outcome type. Always `timeout`. - - `max_output_tokens: Integer` + - `:timeout` - 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). + - `class Exit` - - `max_tool_calls: Integer` + Indicates that the shell commands finished and returned an exit code. - 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. + - `exit_code: Integer` - - `moderation: Moderation{ input, output}` + Exit code from the shell process. - Moderation results for the response input and output, if moderated completions were requested. + - `type: :exit` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + The outcome type. Always `exit`. - Moderation for the response input. + - `:exit` - - `class ModerationResult` + - `stderr: String` - A moderation result produced for the response input or output. + The standard error output that was captured. - - `categories: Hash[Symbol, bool]` + - `stdout: String` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The standard output that was captured. - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `created_by: String` - Which modalities of input are reflected by the score for each category. + The identifier of the actor that created the item. - - `:text` + - `status: :in_progress | :completed | :incomplete` - - `:image` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `category_scores: Hash[Symbol, Float]` + - `:in_progress` - A dictionary of moderation categories to scores. + - `:completed` - - `flagged: bool` + - `:incomplete` - A boolean indicating whether the content was flagged by any category. + - `type: :shell_call_output` - - `model: String` + The type of the shell call output. Always `shell_call_output`. - The moderation model that produced this result. + - `:shell_call_output` - - `type: :moderation_result` + - `agent: Agent{ agent_name}` - The object type, which was always `moderation_result` for successful moderation results. + The agent that produced this item. - - `:moderation_result` + - `agent_name: String` - - `class Error` + The canonical name of the agent that produced this item. - An error produced while attempting moderation for the response input or output. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `code: String` + The execution context that produced this tool call. - The error code. + - `class Direct` - - `message: String` + - `type: :direct` - The error message. + - `:direct` - - `type: :error` + - `class Program` - 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: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `type: :program` - Moderation for the response output. + - `:program` - - `class ModerationResult` + - `created_by: String` - A moderation result produced for the response input or output. + The identifier of the actor that created the item. - - `categories: Hash[Symbol, bool]` + - `class BetaResponseApplyPatchToolCall` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + A tool call that applies file diffs by creating, deleting, or updating files. - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `id: String` - Which modalities of input are reflected by the score for each category. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `:text` + - `call_id: String` - - `:image` + The unique ID of the apply patch tool call generated by the model. - - `category_scores: Hash[Symbol, Float]` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - A dictionary of moderation categories to scores. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `flagged: bool` + - `class CreateFile` - A boolean indicating whether the content was flagged by any category. + Instruction describing how to create a file via the apply_patch tool. - - `model: String` + - `diff: String` - The moderation model that produced this result. + Diff to apply. - - `type: :moderation_result` + - `path: String` - The object type, which was always `moderation_result` for successful moderation results. + Path of the file to create. - - `:moderation_result` + - `type: :create_file` - - `class Error` + Create a new file with the provided diff. - An error produced while attempting moderation for the response input or output. + - `:create_file` - - `code: String` + - `class DeleteFile` - The error code. + Instruction describing how to delete a file via the apply_patch tool. - - `message: String` + - `path: String` - The error message. + Path of the file to delete. - - `type: :error` + - `type: :delete_file` - The object type, which was always `error` for moderation failures. + Delete the specified file. - - `:error` + - `:delete_file` - - `previous_response_id: String` + - `class UpdateFile` - 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`. + Instruction describing how to update a file via the apply_patch tool. - - `prompt: BetaResponsePrompt` + - `diff: String` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Diff to apply. - - `id: String` + - `path: String` - The unique identifier of the prompt template to use. + Path of the file to update. - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `type: :update_file` - 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. + Update an existing file with the provided diff. - - `String = String` + - `:update_file` - - `class BetaResponseInputText` + - `status: :in_progress | :completed` - A text input to the model. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class BetaResponseInputImage` + - `:in_progress` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:completed` - - `class BetaResponseInputFile` + - `type: :apply_patch_call` - A file input to the model. + The type of the item. Always `apply_patch_call`. - - `version: String` + - `:apply_patch_call` - Optional version of the prompt template. + - `agent: Agent{ agent_name}` - - `prompt_cache_key: String` + 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). + - `agent_name: String` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + The canonical name of the agent that produced this item. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `mode: :implicit | :explicit` + The execution context that produced this tool call. - Whether implicit prompt-cache breakpoints were enabled. + - `class Direct` - - `:implicit` + - `type: :direct` - - `:explicit` + - `:direct` - - `ttl: :"30m"` + - `class Program` - The minimum lifetime applied to each cache breakpoint. + - `caller_id: String` - - `:"30m"` + The call ID of the program item that produced this tool call. - - `prompt_cache_retention: :in_memory | :"24h"` + - `type: :program` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `:program` - 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. + - `created_by: String` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The ID of the entity that created this tool call. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `class BetaResponseApplyPatchToolCallOutput` - - `:in_memory` + The output emitted by an apply patch tool call. - - `:"24h"` + - `id: String` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - **gpt-5 and o-series models only** + - `call_id: String` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The unique ID of the apply patch tool call generated by the model. - - `context: :auto | :current_turn | :all_turns` + - `status: :completed | :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. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `:auto` + - `:completed` - - `:current_turn` + - `:failed` - - `:all_turns` + - `type: :apply_patch_call_output` - - `effort: :none | :minimal | :low | 4 more` + The type of the item. Always `apply_patch_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. + - `:apply_patch_call_output` - - `:none` + - `agent: Agent{ agent_name}` - - `:minimal` + The agent that produced this item. - - `:low` + - `agent_name: String` - - `:medium` + The canonical name of the agent that produced this item. - - `:high` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:xhigh` + The execution context that produced this tool call. - - `:max` + - `class Direct` - - `generate_summary: :auto | :concise | :detailed` + - `type: :direct` - **Deprecated:** use `summary` instead. + - `:direct` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `class Program` - - `:auto` + - `caller_id: String` - - `:concise` + The call ID of the program item that produced this tool call. - - `:detailed` + - `type: :program` - - `mode: String | :standard | :pro` + - `:program` - Controls the reasoning execution mode for the request. + - `created_by: String` - When returned on a response, this is the effective execution mode. + The ID of the entity that created this tool call output. - - `String = String` + - `output: String` - - `Mode = :standard | :pro` + Optional textual output returned by the apply patch tool. - Controls the reasoning execution mode for the request. + - `class McpListTools` - When returned on a response, this is the effective execution mode. + A list of tools available on an MCP server. - - `:standard` + - `id: String` - - `:pro` + The unique ID of the list. - - `summary: :auto | :concise | :detailed` + - `server_label: String` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The label of the MCP server. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `:auto` + The tools available on the server. - - `:concise` + - `input_schema: untyped` - - `:detailed` + The JSON schema describing the tool's input. - - `safety_identifier: String` + - `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 name of the tool. - - `service_tier: :auto | :default | :flex | 2 more` + - `annotations: untyped` - Specifies the processing type used for serving the request. + Additional annotations about the tool. - - 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'. + - `description: String` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The description of the tool. - - `:auto` + - `type: :mcp_list_tools` - - `:default` + The type of the item. Always `mcp_list_tools`. - - `:flex` + - `:mcp_list_tools` - - `:scale` + - `agent: Agent{ agent_name}` - - `:priority` + The agent that produced this item. - - `status: BetaResponseStatus` + - `agent_name: String` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The canonical name of the agent that produced this item. - - `:completed` + - `error: String` - - `:failed` + Error message if the server could not list tools. - - `:in_progress` + - `class McpApprovalRequest` - - `:cancelled` + A request for human approval of a tool invocation. - - `:queued` + - `id: String` - - `:incomplete` + The unique ID of the approval request. - - `text: BetaResponseTextConfig` + - `arguments: String` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + A JSON string of arguments for the tool. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `name: String` - - `format_: BetaResponseFormatTextConfig` + The name of the tool to run. - An object specifying the format that the model must output. + - `server_label: 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 label of the MCP server making the request. - The default format is `{ "type": "text" }` with no additional options. + - `type: :mcp_approval_request` - **Not recommended for gpt-4o and newer models:** + The type of the item. Always `mcp_approval_request`. - 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. + - `:mcp_approval_request` - - `class Text` + - `agent: Agent{ agent_name}` - Default response format. Used to generate text responses. + The agent that produced this item. - - `type: :text` + - `agent_name: String` - The type of response format being defined. Always `text`. + The canonical name of the agent that produced this item. - - `:text` + - `class McpApprovalResponse` - - `class BetaResponseFormatTextJSONSchemaConfig` + A response to an MCP approval request. - 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` - - `name: String` + The unique ID of the approval response - 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. + - `approval_request_id: String` - - `schema: Hash[Symbol, untyped]` + The ID of the approval request being answered. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `approve: bool` - - `type: :json_schema` + Whether the request was approved. - The type of response format being defined. Always `json_schema`. + - `type: :mcp_approval_response` - - `:json_schema` + The type of the item. Always `mcp_approval_response`. - - `description: String` + - `:mcp_approval_response` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent: Agent{ agent_name}` - - `strict: bool` + 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). + - `agent_name: String` - - `class JSONObject` + The canonical name of 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. + - `reason: String` - - `type: :json_object` + Optional reason for the decision. - The type of response format being defined. Always `json_object`. + - `class McpCall` - - `:json_object` + An invocation of a tool on an MCP server. - - `verbosity: :low | :medium | :high` + - `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 tool call. - - `:low` + - `arguments: String` - - `:medium` + A JSON string of the arguments passed to the tool. - - `:high` + - `name: String` - - `top_logprobs: Integer` + The name of the tool that was run. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `server_label: String` - - `truncation: :auto | :disabled` + The label of the MCP server running the tool. - The truncation strategy to use for the model response. + - `type: :mcp_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. + The type of the item. Always `mcp_call`. - - `:auto` + - `:mcp_call` - - `:disabled` + - `agent: Agent{ agent_name}` - - `usage: BetaResponseUsage` + The agent that produced this item. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `agent_name: String` - - `input_tokens: Integer` + The canonical name of the agent that produced this item. - The number of input tokens. + - `approval_request_id: String` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + 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 detailed breakdown of the input tokens. + - `error: String` - - `cache_write_tokens: Integer` + The error from the tool call, if any. - The number of input tokens that were written to the cache. + - `output: String` - - `cached_tokens: Integer` + The output from the tool call. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `status: :in_progress | :completed | :incomplete | 2 more` - - `output_tokens: Integer` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The number of output tokens. + - `:in_progress` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `:completed` - A detailed breakdown of the output tokens. + - `:incomplete` - - `reasoning_tokens: Integer` + - `:calling` - The number of reasoning tokens. + - `:failed` - - `total_tokens: Integer` + - `class BetaResponseCustomToolCallItem` - The total number of tokens used. + A call to a custom tool created by the model. - - `user: String` + - `id: String` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The unique ID of the custom tool call item. - - `sequence_number: Integer` + - `status: :in_progress | :completed | :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.in_progress"` + - `:in_progress` - The type of the event. Always `response.in_progress`. + - `:completed` - - `:"response.in_progress"` + - `:incomplete` - - `agent: Agent{ agent_name}` + - `created_by: String` - The agent that owns this multi-agent streaming event. + The identifier of the actor that created the item. - - `agent_name: String` + - `class BetaResponseCustomToolCallOutputItem` - 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. -### Beta Response Includable + - `id: String` -- `BetaResponseIncludable = :"file_search_call.results" | :"web_search_call.results" | :"web_search_call.action.sources" | 5 more` + The unique ID of the custom tool call output item. - Specify additional output data to include in the model response. Currently supported values are: + - `status: :in_progress | :completed | :incomplete` - - `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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:"file_search_call.results"` + - `:in_progress` - - `:"web_search_call.results"` + - `:completed` - - `:"web_search_call.action.sources"` + - `:incomplete` - - `:"message.input_image.image_url"` + - `created_by: String` - - `:"computer_call_output.output.image_url"` + The identifier of the actor that created the item. - - `:"code_interpreter_call.outputs"` +### Beta Response Local Environment - - `:"reasoning.encrypted_content"` +- `class BetaResponseLocalEnvironment` - - `:"message.output_text.logprobs"` + Represents the use of a local environment to perform shell actions. -### Beta Response Incomplete Event + - `type: :local` -- `class BetaResponseIncompleteEvent` + The environment type. Always `local`. - An event that is emitted when a response finishes as incomplete. + - `:local` - - `response: BetaResponse` +### Beta Response Mcp Call Arguments Delta Event - The response that was incomplete. +- `class BetaResponseMcpCallArgumentsDeltaEvent` - - `id: String` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - Unique identifier for this Response. + - `delta: String` - - `created_at: Float` + A JSON string containing the partial update to the arguments for the MCP tool call. - Unix timestamp (in seconds) of when this Response was created. + - `item_id: String` - - `error: BetaResponseError` + The unique identifier of the MCP tool call item being processed. - An error object returned when the model fails to generate a Response. + - `output_index: Integer` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + The index of the output item in the response's output array. - The error code for the response. + - `sequence_number: Integer` - - `:server_error` + The sequence number of this event. - - `:rate_limit_exceeded` + - `type: :"response.mcp_call_arguments.delta"` - - `:invalid_prompt` + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `:bio_policy` + - `:"response.mcp_call_arguments.delta"` - - `:vector_store_timeout` + - `agent: Agent{ agent_name}` - - `:invalid_image` + The agent that owns this multi-agent streaming event. - - `:invalid_image_format` + - `agent_name: String` - - `:invalid_base64_image` + The canonical name of the agent that produced this item. - - `:invalid_image_url` +### Beta Response Mcp Call Arguments Done Event - - `:image_too_large` +- `class BetaResponseMcpCallArgumentsDoneEvent` - - `:image_too_small` + Emitted when the arguments for an MCP tool call are finalized. - - `:image_parse_error` + - `arguments: String` - - `:image_content_policy_violation` + A JSON string containing the finalized arguments for the MCP tool call. - - `:invalid_image_mode` + - `item_id: String` - - `:image_file_too_large` + The unique identifier of the MCP tool call item being processed. - - `:unsupported_image_media_type` + - `output_index: Integer` - - `:empty_image_file` + The index of the output item in the response's output array. - - `:failed_to_download_image` + - `sequence_number: Integer` - - `:image_file_not_found` + The sequence number of this event. - - `message: String` + - `type: :"response.mcp_call_arguments.done"` - A human-readable description of the error. + The type of the event. Always 'response.mcp_call_arguments.done'. - - `incomplete_details: IncompleteDetails{ reason}` + - `:"response.mcp_call_arguments.done"` - Details about why the response is incomplete. + - `agent: Agent{ agent_name}` - - `reason: :max_output_tokens | :content_filter` + The agent that owns this multi-agent streaming event. - The reason why the response is incomplete. + - `agent_name: String` - - `:max_output_tokens` + The canonical name of the agent that produced this item. - - `:content_filter` +### Beta Response Mcp Call Completed Event - - `instructions: String | Array[BetaResponseInputItem]` +- `class BetaResponseMcpCallCompletedEvent` - A system (or developer) message inserted into the model's context. + Emitted when an MCP tool call has completed successfully. - 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. + - `item_id: String` - - `String = String` + The ID of the MCP tool call item that completed. - A text input to the model, equivalent to a text input with the - `developer` role. + - `output_index: Integer` - - `InputItemList = Array[BetaResponseInputItem]` + The index of the output item that completed. - A list of one or many input items to the model, containing - different content types. + - `sequence_number: Integer` - - `class BetaEasyInputMessage` + The sequence number of this event. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `type: :"response.mcp_call.completed"` - - `content: String | BetaResponseInputMessageContentList` + The type of the event. Always 'response.mcp_call.completed'. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `:"response.mcp_call.completed"` - - `String = String` + - `agent: Agent{ agent_name}` - A text input to the model. + The agent that owns this multi-agent streaming event. - - `BetaResponseInputMessageContentList = Array[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. - - `class BetaResponseInputText` +### Beta Response Mcp Call Failed Event - A text input to the model. +- `class BetaResponseMcpCallFailedEvent` - - `text: String` + Emitted when an MCP tool call has failed. - The text input to the model. + - `item_id: String` - - `type: :input_text` + The ID of the MCP tool call item that failed. - The type of the input item. Always `input_text`. + - `output_index: Integer` - - `:input_text` + The index of the output item that failed. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `sequence_number: Integer` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The sequence number of this event. - - `mode: :explicit` + - `type: :"response.mcp_call.failed"` - The breakpoint mode. Always `explicit`. + The type of the event. Always 'response.mcp_call.failed'. - - `:explicit` + - `:"response.mcp_call.failed"` - - `class BetaResponseInputImage` + - `agent: Agent{ agent_name}` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The agent that owns this multi-agent streaming event. - - `detail: :low | :high | :auto | :original` + - `agent_name: String` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The canonical name of the agent that produced this item. - - `:low` +### Beta Response Mcp Call In Progress Event - - `:high` +- `class BetaResponseMcpCallInProgressEvent` - - `:auto` + Emitted when an MCP tool call is in progress. - - `:original` + - `item_id: String` - - `type: :input_image` + The unique identifier of the MCP tool call item being processed. - The type of the input item. Always `input_image`. + - `output_index: Integer` - - `:input_image` + The index of the output item in the response's output array. - - `file_id: String` + - `sequence_number: Integer` - The ID of the file to be sent to the model. + The sequence number of this event. - - `image_url: String` + - `type: :"response.mcp_call.in_progress"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The type of the event. Always 'response.mcp_call.in_progress'. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"response.mcp_call.in_progress"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `agent: Agent{ agent_name}` - - `mode: :explicit` + The agent that owns this multi-agent streaming event. - The breakpoint mode. Always `explicit`. + - `agent_name: String` - - `:explicit` + The canonical name of the agent that produced this item. - - `class BetaResponseInputFile` +### Beta Response Mcp List Tools Completed Event - A file input to the model. +- `class BetaResponseMcpListToolsCompletedEvent` - - `type: :input_file` + Emitted when the list of available MCP tools has been successfully retrieved. - The type of the input item. Always `input_file`. + - `item_id: String` - - `:input_file` + The ID of the MCP tool call item that produced this output. - - `detail: :auto | :low | :high` + - `output_index: Integer` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The index of the output item that was processed. - - `:auto` + - `sequence_number: Integer` - - `:low` + The sequence number of this event. - - `:high` + - `type: :"response.mcp_list_tools.completed"` - - `file_data: String` + The type of the event. Always 'response.mcp_list_tools.completed'. - The content of the file to be sent to the model. + - `:"response.mcp_list_tools.completed"` - - `file_id: String` + - `agent: Agent{ agent_name}` - The ID of the file to be sent to the model. + The agent that owns this multi-agent streaming event. - - `file_url: 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: String` +### Beta Response Mcp List Tools Failed Event - The name of the file to be sent to the model. +- `class BetaResponseMcpListToolsFailedEvent` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Emitted when the attempt to list available MCP tools has failed. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `item_id: String` - - `mode: :explicit` + The ID of the MCP tool call item that failed. - The breakpoint mode. Always `explicit`. + - `output_index: Integer` - - `:explicit` + The index of the output item that failed. - - `role: :user | :assistant | :system | :developer` + - `sequence_number: Integer` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The sequence number of this event. - - `:user` + - `type: :"response.mcp_list_tools.failed"` - - `:assistant` + The type of the event. Always 'response.mcp_list_tools.failed'. - - `:system` + - `:"response.mcp_list_tools.failed"` - - `:developer` + - `agent: Agent{ agent_name}` - - `phase: :commentary` + The agent that owns this multi-agent streaming event. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `agent_name: String` - - `:commentary` + The canonical name of the agent that produced this item. - - `type: :message` +### Beta Response Mcp List Tools In Progress Event - The type of the message input. Always `message`. +- `class BetaResponseMcpListToolsInProgressEvent` - - `:message` + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `class Message` + - `item_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 ID of the MCP tool call item that is being processed. - - `content: BetaResponseInputMessageContentList` + - `output_index: Integer` - A list of one or many input items to the model, containing different content - types. + The index of the output item that is being processed. - - `role: :user | :system | :developer` + - `sequence_number: Integer` - The role of the message input. One of `user`, `system`, or `developer`. + The sequence number of this event. - - `:user` + - `type: :"response.mcp_list_tools.in_progress"` - - `:system` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `:developer` + - `:"response.mcp_list_tools.in_progress"` - `agent: Agent{ 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: :in_progress | :completed | :incomplete` +### Beta Response Output Audio - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +- `class BetaResponseOutputAudio` + + An audio output from the model. + + - `data: String` + + Base64-encoded audio data from the model. + + - `transcript: String` + + The transcript of the audio data from the model. - - `:in_progress` + - `type: :output_audio` - - `:completed` + The type of the output audio. Always `output_audio`. - - `:incomplete` + - `:output_audio` - - `type: :message` +### Beta Response Output Item - The type of the message input. Always set to `message`. +- `BetaResponseOutputItem = BetaResponseOutputMessage | BetaResponseFileSearchToolCall | BetaResponseFunctionToolCall | 28 more` - - `:message` + An output message from the model. - `class BetaResponseOutputMessage` @@ -87808,7 +99991,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -87816,6 +99999,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -87892,34 +100077,64 @@ puts(beta_compacted_response) The text that was retrieved from the file. - - `class BetaResponseComputerToolCall` + - `class BetaResponseFunctionToolCall` - 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](https://platform.openai.com/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[PendingSafetyCheck{ id, code, message}]` + - `name: String` - The pending safety checks for the computer call. + The name of the function to run. + + - `type: :function_call` + + The type of the function tool call. Always `function_call`. + + - `:function_call` - `id: String` - The ID of the pending safety check. + The unique ID of the function tool call. - - `code: String` + - `agent: Agent{ agent_name}` - The type of the pending safety check. + The agent that produced this item. - - `message: String` + - `agent_name: String` - Details about the pending safety check. + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` @@ -87932,274 +100147,275 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :computer_call` + - `class BetaResponseFunctionToolCallOutputItem` - The type of the computer call. Always `computer_call`. + - `id: String` - - `:computer_call` + The unique ID of the function call tool output. - - `action: BetaComputerAction` + - `call_id: String` - A click action. + The unique ID of the function tool call generated by the model. - - `class Click` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | 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 | :right | :wheel | 2 more` + - `String = 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[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:right` + Text, image, or file output of the function call. - - `:wheel` + - `class BetaResponseInputText` - - `: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: Integer` + - `:input_text` - The x-coordinate where the click occurred. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `y_: Integer` + Marks the exact end of a reusable 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: Array[String]` + The breakpoint mode. Always `explicit`. - The keys being held while clicking. + - `:explicit` - - `class DoubleClick` + - `class BetaResponseInputImage` - A double click action. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `keys: Array[String]` + - `detail: :low | :high | :auto | :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: Integer` + - `:original` - The x-coordinate where the double click occurred. + - `type: :input_image` - - `y_: Integer` + The type of the input item. Always `input_image`. - The y-coordinate where the double click occurred. + - `:input_image` - - `class Drag` + - `file_id: String` - A drag action. + The ID of the file to be sent to the model. - - `path: Array[Path{ x, y_}]` + - `image_url: 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: PromptCacheBreakpoint{ mode}` - - `x: Integer` + Marks the exact end of a reusable 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_: Integer` + The breakpoint mode. Always `explicit`. - The y-coordinate. + - `:explicit` - - `type: :drag` + - `class BetaResponseInputFile` - 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: Array[String]` + The type of the input item. Always `input_file`. - The keys being held while dragging the mouse. + - `:input_file` - - `class Keypress` + - `detail: :auto | :low | :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[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: String` - - `:keypress` + The content of the file to be sent to the model. - - `class Move` + - `file_id: String` - A mouse move action. + The ID of the file to be sent to the model. - - `type: :move` + - `file_url: 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: String` - - `x: Integer` + The name of the file to be sent to the model. - The x-coordinate to move to. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `y_: Integer` + Marks the exact end of a reusable 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: Array[String]` + The breakpoint mode. Always `explicit`. - The keys being held while moving the mouse. + - `:explicit` - - `class Screenshot` + - `status: :in_progress | :completed | :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` - - `class Scroll` + - `type: :function_call_output` - A scroll action. + The type of the function tool call output. Always `function_call_output`. - - `scroll_x: Integer` + - `:function_call_output` - The horizontal scroll distance. + - `agent: Agent{ agent_name}` - - `scroll_y: Integer` + 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_: Direct{ type} | Program{ caller_id, type}` - - `:scroll` + The execution context that produced this tool call. - - `x: Integer` + - `class Direct` - The x-coordinate where the scroll occurred. + - `type: :direct` - - `y_: Integer` + The caller type. Always `direct`. - The y-coordinate where the scroll occurred. + - `:direct` - - `keys: Array[String]` + - `class Program` - The keys being held while scrolling. + - `caller_id: String` - - `class 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: 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` + - `class AgentMessage` - - `class Wait` + - `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[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `actions: BetaComputerActionList` + Encrypted content sent between agents. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `class BetaResponseInputText` - - `class Click` + A text input to the model. - A click action. + - `class BetaResponseOutputText` - - `class DoubleClick` + A text output from the model. - A double click action. + - `class Text` - - `class Drag` + A text content. - A drag action. + - `text: String` - - `class Keypress` + - `type: :text` - A collection of keypresses the model would like to perform. + - `:text` - - `class Move` + - `class SummaryText` - A mouse move action. + A summary text from the model. - - `class Screenshot` + - `text: String` - A screenshot action. + A summary of the reasoning output from the model so far. - - `class Scroll` + - `type: :summary_text` - A scroll action. + The type of the object. Always `summary_text`. - - `class Type` + - `:summary_text` - An action to type in text. + - `class ReasoningText` - - `class Wait` + Reasoning text from the model. - A wait action. + - `text: String` - - `agent: Agent{ 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` - - `class ComputerCallOutput` + - `class BetaResponseOutputRefusal` - The output of a computer tool call. + A refusal from the model. - - `call_id: String` + - `class BetaResponseInputImage` - The ID of the computer tool call that produced the output. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `class ComputerScreenshot` - A computer screenshot image used with the computer use tool. + A screenshot of a computer. - - `type: :computer_screenshot` + - `detail: :low | :high | :auto | :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` + + - `:high` + + - `:auto` + + - `:original` - `file_id: String` @@ -88209,31 +100425,93 @@ puts(beta_compacted_response) 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: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: Array[AcknowledgedSafetyCheck{ 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` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `class EncryptedContent` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` - `id: String` - The ID of the pending safety check. + The unique ID of the multi-agent call item. - - `code: String` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The type of the pending safety check. + The multi-agent action to execute. - - `message: 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: Agent{ agent_name}` @@ -88243,15 +100521,63 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `class MultiAgentCallOutput` - 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 | :interrupt_agent | :list_agents | 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[BetaResponseOutputText]` + + Text output returned by the multi-agent action. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ 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: Array[Logprob{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. - `class BetaResponseFunctionWebSearch` @@ -88357,349 +100683,360 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall` + - `class BetaResponseComputerToolCall` - 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](https://platform.openai.com/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[PendingSafetyCheck{ 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: String` - - `id: String` + The type of the pending safety check. - The unique ID of the function tool call. + - `message: String` - - `agent: Agent{ agent_name}` + Details about the pending safety check. - The agent that produced this item. + - `status: :in_progress | :completed | :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_: Direct{ type} | Program{ caller_id, type}` + - `:completed` - The execution context that produced this tool call. + - `:incomplete` - - `class Direct` + - `type: :computer_call` - - `type: :direct` + The type of the computer call. Always `computer_call`. - - `:direct` + - `:computer_call` - - `class Program` + - `action: BetaComputerAction` - - `caller_id: String` + A click action. - The call ID of the program item that produced this tool call. + - `class Click` - - `type: :program` + A click action. - - `:program` + - `button: :left | :right | :wheel | 2 more` - - `namespace: 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: :in_progress | :completed | :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` - - `class FunctionCallOutput` + 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: Integer` - The unique ID of the function tool call generated by the model. + The x-coordinate where the click occurred. - - `output: String | BetaResponseFunctionCallOutputItemList` + - `y_: Integer` - Text, image, or file output of the function tool call. + The y-coordinate where the click occurred. - - `String = String` + - `keys: Array[String]` - A JSON string of the output of the function tool call. + The keys being held while clicking. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `class DoubleClick` - An array of content outputs (text, image, file) for the function tool call. + A double click action. - - `class BetaResponseInputTextContent` + - `keys: Array[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: Integer` - - `:input_text` + The x-coordinate where the double click occurred. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `y_: Integer` - Marks the exact end of a reusable 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` + - `class Drag` - The breakpoint mode. Always `explicit`. + A drag action. - - `:explicit` + - `path: Array[Path{ x, y_}]` - - `class BetaResponseInputImageContent` + 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: Integer` - The type of the input item. Always `input_image`. + The x-coordinate. - - `:input_image` + - `y_: Integer` - - `detail: :low | :high | :auto | :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: Array[String]` - - `:original` + The keys being held while dragging the mouse. - - `file_id: String` + - `class Keypress` - The ID of the file to be sent to the model. + A collection of keypresses the model would like to perform. - - `image_url: String` + - `keys: Array[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: PromptCacheBreakpoint{ 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`. + - `class Move` - - `:explicit` + A mouse move action. - - `class BetaResponseInputFileContent` + - `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: Integer` - - `:input_file` + The x-coordinate to move to. - - `detail: :auto | :low | :high` + - `y_: Integer` - 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: Array[String]` - - `:low` + The keys being held while moving the mouse. - - `:high` + - `class Screenshot` - - `file_data: String` + A screenshot action. - The base64-encoded data of the file to be sent to the model. + - `type: :screenshot` - - `file_id: 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: String` + - `class Scroll` - The URL of the file to be sent to the model. + A scroll action. - - `filename: String` + - `scroll_x: Integer` - The name of the file to be sent to the model. + The horizontal scroll distance. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `scroll_y: Integer` - Marks the exact end of a reusable 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: Integer` - The type of the function tool call output. Always `function_call_output`. + The x-coordinate where the scroll occurred. - - `:function_call_output` + - `y_: Integer` - - `id: 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: Array[String]` - - `agent: Agent{ agent_name}` + The keys being held while scrolling. - The agent that produced this item. + - `class Type` - - `agent_name: String` + An action to type in text. - The canonical name of the agent that produced this item. + - `text: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The text to type. - The execution context that produced this tool call. + - `type: :type` - - `class Direct` + Specifies the event type. For a type action, this property is always set to `type`. - - `type: :direct` + - `:type` - The caller type. Always `direct`. + - `class Wait` - - `:direct` + A wait action. - - `class Program` + - `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: BetaComputerActionList` - The caller type. Always `program`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `:program` + - `class Click` - - `status: :in_progress | :completed | :incomplete` + A click action. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `class DoubleClick` - - `:in_progress` + A double click action. - - `:completed` + - `class Drag` - - `:incomplete` + A drag action. - - `class AgentMessage` + - `class Keypress` - A message routed between agents. + A collection of keypresses the model would like to perform. - - `author: String` + - `class Move` - The sending agent identity. + A mouse move action. - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + - `class Screenshot` - Plaintext, image, or encrypted content sent between agents. + A screenshot action. - - `class BetaResponseInputTextContent` + - `class Scroll` - A text input to the model. + A scroll action. - - `class BetaResponseInputImageContent` + - `class Type` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + An action to type in text. - - `class EncryptedContent` + - `class Wait` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + A wait action. - - `encrypted_content: String` + - `agent: Agent{ 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` + - `class BetaResponseComputerToolCallOutputItem` - - `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: String` + A computer screenshot image used with the computer use tool. - The unique ID of this agent message item. + - `type: :computer_screenshot` - - `agent: Agent{ 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: String` - The canonical name of the agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `class MultiAgentCall` + - `image_url: String` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The URL of the screenshot image. - The multi-agent action that was executed. + - `status: :completed | :incomplete | :failed | :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: Array[AcknowledgedSafetyCheck{ 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: String` - - `id: String` + The type of the pending safety check. - The unique ID of this multi-agent call. + - `message: String` + + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -88709,127 +101046,138 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput` + - `created_by: String` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The identifier of the actor that created the item. - The multi-agent action that produced this result. + - `class BetaResponseReasoningItem` - - `: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](https://platform.openai.com/docs/guides/conversation-state). - - `:interrupt_agent` + - `id: String` - - `:list_agents` + The unique identifier of the reasoning content. - - `:send_message` + - `summary: Array[Summary{ 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[Output{ 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: Agent{ agent_name}` - - `:output_text` + The agent that produced this item. - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ 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. - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `content: Array[Content{ 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: Integer` + 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: 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: :in_progress | :completed | :incomplete` - - `UnionMember1 = Array[UnionMember1{ 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: Integer` + - `:in_progress` - The index of the last character of the citation in the message. + - `:completed` - - `start_index: Integer` + - `:incomplete` - The index of the first character of the citation in the message. + - `class Program` - - `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` - - `UnionMember2 = Array[UnionMember2{ 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: Integer` + - `:program` - The index of the last character of the citation in the message. + - `agent: Agent{ 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. + - `class ProgramOutput` - - `start_index: Integer` + - `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 | :incomplete` - - `:multi_agent_call_output` + The terminal status of the program output item. - - `id: 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: Agent{ agent_name}` @@ -88839,29 +101187,61 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall` + - `class BetaResponseToolSearchCall` + + - `id: String` + + The unique ID of the tool search call item. - `arguments: untyped` - 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 | :client` - - `id: 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 | :completed | :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: Agent{ agent_name}` The agent that produced this item. - - `agent_name: String` + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` + + - `id: String` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - `call_id: String` @@ -88877,7 +101257,7 @@ puts(beta_compacted_response) - `status: :in_progress | :completed | :incomplete` - The status of the tool search call. + The status of the tool search output item that was recorded. - `:in_progress` @@ -88885,11 +101265,9 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseToolSearchOutputItemParam` - - `tools: Array[BetaTool]` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool` @@ -88988,7 +101366,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -88998,7 +101376,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -89045,7 +101427,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -89055,7 +101437,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -89979,14 +102365,10 @@ puts(beta_compacted_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: String` - - The unique ID of this tool search output. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -89995,39 +102377,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` - - The unique ID of the tool search call generated by the model. + - `created_by: String` - - `execution: :server | :client` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `class AdditionalTools` - - `:server` + - `id: String` - - `:client` + The unique ID of the additional tools item. - - `status: :in_progress | :completed | :incomplete` + - `role: :unknown | :user | :assistant | 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `:in_progress` + - `:unknown` - - `:completed` + - `:user` - - `:incomplete` + - `:assistant` - - `class AdditionalTools` + - `:system` - - `role: :developer` + - `:critic` - The role that provided the additional tools. Only `developer` is supported. + - `:discriminator` - `:developer` + - `:tool` + - `tools: Array[BetaTool]` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `class BetaFunctionTool` @@ -90053,1017 +102435,51 @@ puts(beta_compacted_response) - `class Mcp` 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). - - - `class CodeInterpreter` - - A tool that runs Python code to help generate a response to a prompt. - - - `class ProgrammaticToolCalling` - - - `class ImageGeneration` - - A tool that generates images using the GPT image models. - - - `class LocalShell` - - A tool that allows the model to execute shell commands in a local environment. - - - `class BetaFunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool` - - 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) - - - `class BetaNamespaceTool` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool` - - 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). - - - `class BetaApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :additional_tools` - - The item type. Always `additional_tools`. - - - `:additional_tools` - - - `id: String` - - The unique ID of this additional tools item. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class BetaResponseReasoningItem` - - 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[Summary{ 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `content: Array[Content{ 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: String` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class BetaResponseCompactionItemParam` - - 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: String` - - The ID of the compaction item. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class ImageGenerationCall` - - 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 | :completed | :generating | :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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall` - - 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[Logs{ logs, type} | Image{ type, url}]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class Logs` - - 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` - - - `class Image` - - 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 | :completed | :incomplete | 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class LocalShellCall` - - A tool call to run a command on the local shell. - - - `id: String` - - The unique ID of the local shell call. - - - `action: Action{ command, env, type, 3 more}` - - Execute a shell command on the server. - - - `command: Array[String]` - - The command to run. - - - `env: Hash[Symbol, String]` - - Environment variables to set for the command. - - - `type: :exec` - - The type of the local shell action. Always `exec`. - - - `:exec` - - - `timeout_ms: Integer` - - Optional timeout in milliseconds for the command. - - - `user: String` - - Optional user to run the command as. - - - `working_directory: 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 | :completed | :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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class LocalShellCallOutput` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ShellCall` - - A tool representing a request to execute one or more shell commands. - - - `action: Action{ commands, max_output_length, timeout_ms}` - - The shell commands and limits that describe how to run the tool call. - - - `commands: Array[String]` - - Ordered shell commands for the execution environment to run. - - - `max_output_length: Integer` - - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - - `timeout_ms: Integer` - - 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: String` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - The caller type. Always `program`. - - - `:program` - - - `environment: BetaLocalEnvironment | BetaContainerReference` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment` - - - `class BetaContainerReference` - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ShellCallOutput` - - 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[BetaResponseFunctionShellCallOutputContent]` - - Captured chunks of stdout and stderr output, along with their associated outcomes. - - - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - The exit or timeout outcome associated with this shell call. - - - `class Timeout` - - Indicates that the shell call exceeded its configured time limit. - - - `type: :timeout` - - The outcome type. Always `timeout`. - - - `:timeout` - - - `class Exit` - - Indicates that the shell commands finished and returned an exit code. - - - `exit_code: Integer` - - 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: String` - - The unique ID of the shell tool call output. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `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: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call output. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ApplyPatchCall` - - 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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - The specific create, delete, or update instruction for the apply_patch tool call. - - - `class CreateFile` - - 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` - - - `class DeleteFile` - - 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` - - - `class UpdateFile` - - 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 | :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: String` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - The caller type. Always `program`. - - - `:program` - - - `class ApplyPatchCallOutput` - - 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 | :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: String` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - The caller type. Always `program`. - - - `:program` - - - `output: String` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `class McpListTools` - - 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[Tool{ input_schema, name, annotations, description}]` - - The tools available on the server. - - - `input_schema: untyped` - - The JSON schema describing the tool's input. - - - `name: String` - - The name of the tool. - - - `annotations: untyped` - - Additional annotations about the tool. - - - `description: String` - - The description of the tool. - - - `type: :mcp_list_tools` - - The type of the item. Always `mcp_list_tools`. - - - `:mcp_list_tools` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `error: String` - - Error message if the server could not list tools. - - - `class McpApprovalRequest` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class McpApprovalResponse` - - A response to an MCP approval request. - - - `approval_request_id: String` - - The ID of the approval request being answered. - - - `approve: bool` - - Whether the request was approved. - - - `type: :mcp_approval_response` - - The type of the item. Always `mcp_approval_response`. - - - `:mcp_approval_response` - - - `id: String` - - The unique ID of the approval response - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `reason: String` - - Optional reason for the decision. - - - `class McpCall` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `approval_request_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. - - - `error: String` - - The error from the tool call, if any. - - - `output: String` - - The output from the tool call. - - - `status: :in_progress | :completed | :incomplete | 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `:calling` - - - `:failed` - - - `class BetaResponseCustomToolCallOutput` - - 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - The output from the custom tool call generated by your code. - Can be a string or an list of output content. - - - `String = String` - - A string of the output of the custom tool call. - - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class BetaResponseInputText` - - A text input to the model. - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile` - - 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: String` - - The unique ID of the custom tool call output in the OpenAI platform. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `type: :direct` + - `class CodeInterpreter` - The caller type. Always `direct`. + A tool that runs Python code to help generate a response to a prompt. - - `:direct` + - `class ProgrammaticToolCalling` - - `class Program` + - `class ImageGeneration` - - `caller_id: String` + A tool that generates images using the GPT image models. - The call ID of the program item that produced this tool call. + - `class LocalShell` - - `type: :program` + A tool that allows the model to execute shell commands in a local environment. - The caller type. Always `program`. + - `class BetaFunctionShellTool` - - `:program` + A tool that allows the model to execute shell commands. - - `class BetaResponseCustomToolCall` + - `class BetaCustomTool` - A call to a custom tool created by 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) - - `call_id: String` + - `class BetaNamespaceTool` - An identifier used to map this custom tool call to a tool call output. + Groups function/custom tools under a shared namespace. - - `input: String` + - `class BetaToolSearchTool` - The input for the custom tool call generated by the model. + Hosted or BYOT tool search configuration for deferred tools. - - `name: String` + - `class BetaWebSearchPreviewTool` - The name of the custom tool being called. + 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: :custom_tool_call` + - `class BetaApplyPatchTool` - The type of the custom tool call. Always `custom_tool_call`. + Allows the assistant to create, delete, or update files using unified diffs. - - `:custom_tool_call` + - `type: :additional_tools` - - `id: String` + The type of the item. Always `additional_tools`. - The unique ID of the custom tool call in the OpenAI platform. + - `:additional_tools` - `agent: Agent{ agent_name}` @@ -91073,55 +102489,65 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseCompactionItem` - The execution context that produced this tool call. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `class Direct` + - `id: String` - - `type: :direct` + The unique ID of the compaction item. - - `:direct` + - `encrypted_content: String` - - `class Program` + The encrypted content that was produced by compaction. - - `caller_id: String` + - `type: :compaction` - The call ID of the program item that produced this tool call. + The type of the item. Always `compaction`. - - `type: :program` + - `:compaction` - - `:program` + - `agent: Agent{ agent_name}` - - `namespace: String` + The agent that produced this item. - The namespace of the custom tool being called. + - `agent_name: String` - - `class CompactionTrigger` + The canonical name of the agent that produced this item. - Compacts the current context. Must be the final input item. + - `created_by: String` - - `type: :compaction_trigger` + The identifier of the actor that created the item. - The type of the item. Always `compaction_trigger`. + - `class ImageGenerationCall` - - `:compaction_trigger` + An image generation request made by the model. - - `agent: Agent{ agent_name}` + - `id: String` - The agent that produced this item. + The unique ID of the image generation call. - - `agent_name: String` + - `result: String` - The canonical name of the agent that produced this item. + The generated image encoded in base64. - - `class ItemReference` + - `status: :in_progress | :completed | :generating | :failed` - An internal identifier for an item to reference. + The status of the image generation call. - - `id: String` + - `:in_progress` - The ID of the item to reference. + - `:completed` + + - `:generating` + + - `:failed` + + - `type: :image_generation_call` + + The type of the image generation call. Always `image_generation_call`. + + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -91131,71 +102557,74 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `type: :item_reference` - - The type of item to reference. Always `item_reference`. - - - `:item_reference` + - `class BetaResponseCodeInterpreterToolCall` - - `class Program` + A tool call to run code. - `id: String` - The unique ID of this program item. + The unique ID of the code interpreter tool call. - - `call_id: String` + - `code: String` - The stable call ID of the program item. + The code to run, or null if not available. - - `code: String` + - `container_id: String` - The JavaScript source executed by programmatic tool calling. + The ID of the container used to run the code. - - `fingerprint: String` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - Opaque program replay fingerprint that must be round-tripped. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: :program` + - `class Logs` - The item type. Always `program`. + The logs output from the code interpreter. - - `:program` + - `logs: String` - - `agent: Agent{ agent_name}` + The logs output from the code interpreter. - The agent that produced this item. + - `type: :logs` - - `agent_name: String` + The type of the output. Always `logs`. - The canonical name of the agent that produced this item. + - `:logs` - - `class ProgramOutput` + - `class Image` - - `id: String` + The image output from the code interpreter. - The unique ID of this program output item. + - `type: :image` - - `call_id: String` + The type of the output. Always `image`. - The call ID of the program item. + - `:image` - - `result: String` + - `url: String` - The result produced by the program item. + The URL of the image output from the code interpreter. - - `status: :completed | :incomplete` + - `status: :in_progress | :completed | :incomplete | 2 more` - The terminal status of the program output. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `:in_progress` - `:completed` - `:incomplete` - - `type: :program_output` + - `:interpreting` - The item type. Always `program_output`. + - `:failed` - - `:program_output` + - `type: :code_interpreter_call` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `:code_interpreter_call` - `agent: Agent{ agent_name}` @@ -91205,291 +102634,271 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `metadata: Hash[Symbol, 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. + - `class LocalShellCall` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A tool call to run a command on the local shell. - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `id: 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 unique ID of the local shell call. - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `action: Action{ command, env, type, 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](https://platform.openai.com/docs/models) - to browse and compare available models. + Execute a shell command on the server. - - `:"gpt-5.6-sol"` + - `command: Array[String]` - - `:"gpt-5.6-terra"` + The command to run. - - `:"gpt-5.6-luna"` + - `env: Hash[Symbol, String]` - - `:"gpt-5.4"` + Environment variables to set for the command. - - `:"gpt-5.4-mini"` + - `type: :exec` - - `:"gpt-5.4-nano"` + The type of the local shell action. Always `exec`. - - `:"gpt-5.4-mini-2026-03-17"` + - `:exec` - - `:"gpt-5.4-nano-2026-03-17"` + - `timeout_ms: Integer` - - `:"gpt-5.3-chat-latest"` + Optional timeout in milliseconds for the command. - - `:"gpt-5.2"` + - `user: String` - - `:"gpt-5.2-2025-12-11"` + Optional user to run the command as. - - `:"gpt-5.2-chat-latest"` + - `working_directory: String` - - `:"gpt-5.2-pro"` + Optional working directory to run the command in. - - `:"gpt-5.2-pro-2025-12-11"` + - `call_id: String` - - `:"gpt-5.1"` + The unique ID of the local shell tool call generated by the model. - - `:"gpt-5.1-2025-11-13"` + - `status: :in_progress | :completed | :incomplete` - - `:"gpt-5.1-codex"` + The status of the local shell call. - - `:"gpt-5.1-mini"` + - `:in_progress` - - `:"gpt-5.1-chat-latest"` + - `:completed` - - `:"gpt-5"` + - `:incomplete` - - `:"gpt-5-mini"` + - `type: :local_shell_call` - - `:"gpt-5-nano"` + The type of the local shell call. Always `local_shell_call`. - - `:"gpt-5-2025-08-07"` + - `:local_shell_call` - - `:"gpt-5-mini-2025-08-07"` + - `agent: Agent{ agent_name}` - - `:"gpt-5-nano-2025-08-07"` + The agent that produced this item. - - `:"gpt-5-chat-latest"` + - `agent_name: String` - - `:"gpt-4.1"` + The canonical name of the agent that produced this item. - - `:"gpt-4.1-mini"` + - `class LocalShellCallOutput` - - `:"gpt-4.1-nano"` + The output of a local shell tool call. - - `:"gpt-4.1-2025-04-14"` + - `id: String` - - `:"gpt-4.1-mini-2025-04-14"` + The unique ID of the local shell tool call generated by the model. - - `:"gpt-4.1-nano-2025-04-14"` + - `output: String` - - `:"o4-mini"` + A JSON string of the output of the local shell tool call. - - `:"o4-mini-2025-04-16"` + - `type: :local_shell_call_output` - - `:o3` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:"o3-2025-04-16"` + - `:local_shell_call_output` - - `:"o3-mini"` + - `agent: Agent{ 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"` + - `status: :in_progress | :completed | :incomplete` - - `:"o1-preview-2024-09-12"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `:"o1-mini"` + - `:in_progress` - - `:"o1-mini-2024-09-12"` + - `:completed` - - `:"gpt-4o"` + - `:incomplete` - - `:"gpt-4o-2024-11-20"` + - `class BetaResponseFunctionShellToolCall` - - `:"gpt-4o-2024-08-06"` + A tool call that executes one or more shell commands in a managed environment. - - `:"gpt-4o-2024-05-13"` + - `id: String` - - `:"gpt-4o-audio-preview"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:"gpt-4o-audio-preview-2024-12-17"` + The shell commands and limits that describe how to run the tool call. - - `:"gpt-4o-audio-preview-2025-06-03"` + - `commands: Array[String]` - - `:"gpt-4o-mini-audio-preview"` + - `max_output_length: Integer` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + Optional maximum number of characters to return from each command. - - `:"gpt-4o-search-preview"` + - `timeout_ms: Integer` - - `:"gpt-4o-mini-search-preview"` + Optional timeout in milliseconds for the commands. - - `:"gpt-4o-search-preview-2025-03-11"` + - `call_id: String` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + The unique ID of the shell tool call generated by the model. - - `:"chatgpt-4o-latest"` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:"codex-mini-latest"` + Represents the use of a local environment to perform shell actions. - - `:"gpt-4o-mini"` + - `class BetaResponseLocalEnvironment` - - `:"gpt-4o-mini-2024-07-18"` + Represents the use of a local environment to perform shell actions. - - `:"gpt-4-turbo"` + - `type: :local` - - `:"gpt-4-turbo-2024-04-09"` + The environment type. Always `local`. - - `:"gpt-4-0125-preview"` + - `:local` - - `:"gpt-4-turbo-preview"` + - `class BetaResponseContainerReference` - - `:"gpt-4-1106-preview"` + Represents a container created with /v1/containers. - - `:"gpt-4-vision-preview"` + - `container_id: String` - - `:"gpt-4"` + - `type: :container_reference` - - `:"gpt-4-0314"` + The environment type. Always `container_reference`. - - `:"gpt-4-0613"` + - `:container_reference` - - `:"gpt-4-32k"` + - `status: :in_progress | :completed | :incomplete` - - `:"gpt-4-32k-0314"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:"gpt-4-32k-0613"` + - `:in_progress` - - `:"gpt-3.5-turbo"` + - `:completed` - - `:"gpt-3.5-turbo-16k"` + - `:incomplete` - - `:"gpt-3.5-turbo-0301"` + - `type: :shell_call` - - `:"gpt-3.5-turbo-0613"` + The type of the item. Always `shell_call`. - - `:"gpt-3.5-turbo-1106"` + - `:shell_call` - - `:"gpt-3.5-turbo-0125"` + - `agent: Agent{ agent_name}` - - `:"gpt-3.5-turbo-16k-0613"` + The agent that produced this item. - - `:"o1-pro"` + - `agent_name: String` - - `:"o1-pro-2025-03-19"` + The canonical name of the agent that produced this item. - - `:"o3-pro"` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:"o3-pro-2025-06-10"` + The execution context that produced this tool call. - - `:"o3-deep-research"` + - `class Direct` - - `:"o3-deep-research-2025-06-26"` + - `type: :direct` - - `:"o4-mini-deep-research"` + - `:direct` - - `:"o4-mini-deep-research-2025-06-26"` + - `class Program` - - `:"computer-use-preview"` + - `caller_id: String` - - `:"computer-use-preview-2025-03-11"` + The call ID of the program item that produced this tool call. - - `:"gpt-5-codex"` + - `type: :program` - - `:"gpt-5-pro"` + - `:program` - - `:"gpt-5-pro-2025-10-06"` + - `created_by: String` - - `:"gpt-5.1-codex-max"` + The ID of the entity that created this tool call. - - `String = String` + - `class BetaResponseFunctionShellToolCallOutput` - - `object: :response` + The output of a shell tool call that was emitted. - The object type of this resource - always set to `response`. + - `id: String` - - `:response` + The unique ID of the shell call output. Populated when this item is returned via API. - - `output: Array[BetaResponseOutputItem]` + - `call_id: String` - An array of content items generated by the model. + The unique ID of the shell tool call 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. + - `max_output_length: Integer` - - `class BetaResponseOutputMessage` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - An output message from the model. + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `class BetaResponseFileSearchToolCall` + An array of shell call output contents - 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. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `class BetaResponseFunctionToolCall` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class Timeout` - - `class BetaResponseFunctionToolCallOutputItem` + Indicates that the shell call exceeded its configured time limit. - - `id: String` + - `type: :timeout` - The unique ID of the function call tool output. + The outcome type. Always `timeout`. - - `call_id: String` + - `:timeout` - The unique ID of the function tool call generated by the model. + - `class Exit` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + Indicates that the shell commands finished and returned an exit code. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `exit_code: Integer` - - `String = String` + Exit code from the shell process. - A string of the output of the function call. + - `type: :exit` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The outcome type. Always `exit`. - Text, image, or file output of the function call. + - `:exit` - - `class BetaResponseInputText` + - `stderr: String` - A text input to the model. + The standard error output that was captured. - - `class BetaResponseInputImage` + - `stdout: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The standard output that was captured. - - `class BetaResponseInputFile` + - `created_by: String` - A file input to the model. + The identifier of the actor that created the item. - `status: :in_progress | :completed | :incomplete` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` @@ -91497,11 +102906,11 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :function_call_output` + - `type: :shell_call_output` - The type of the function tool call output. Always `function_call_output`. + The type of the shell call output. Always `shell_call_output`. - - `:function_call_output` + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -91519,8 +102928,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -91531,149 +102938,149 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - `created_by: String` The identifier of the actor that created the item. - - `class AgentMessage` + - `class BetaResponseApplyPatchToolCall` + + A tool call that applies file diffs by creating, deleting, or updating files. - `id: String` - The unique ID of the agent message. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `author: String` + - `call_id: String` - The sending agent identity. + The unique ID of the apply patch tool call generated by the model. - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - Encrypted content sent between agents. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class BetaResponseInputText` + - `class CreateFile` - A text input to the model. + Instruction describing how to create a file via the apply_patch tool. - - `class BetaResponseOutputText` + - `diff: String` - A text output from the model. + Diff to apply. - - `class Text` + - `path: String` - A text content. + Path of the file to create. - - `text: String` + - `type: :create_file` - - `type: :text` + Create a new file with the provided diff. - - `:text` + - `:create_file` - - `class SummaryText` + - `class DeleteFile` - A summary text from the model. + Instruction describing how to delete a file via the apply_patch tool. - - `text: String` + - `path: String` - A summary of the reasoning output from the model so far. + Path of the file to delete. - - `type: :summary_text` + - `type: :delete_file` - The type of the object. Always `summary_text`. + Delete the specified file. - - `:summary_text` + - `:delete_file` - - `class ReasoningText` + - `class UpdateFile` - Reasoning text from the model. + Instruction describing how to update a file via the apply_patch tool. - - `text: String` + - `diff: String` - The reasoning text from the model. + Diff to apply. - - `type: :reasoning_text` + - `path: String` - The type of the reasoning text. Always `reasoning_text`. + Path of the file to update. - - `:reasoning_text` + - `type: :update_file` - - `class BetaResponseOutputRefusal` + Update an existing file with the provided diff. - A refusal from the model. + - `:update_file` - - `class BetaResponseInputImage` + - `status: :in_progress | :completed` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class ComputerScreenshot` + - `:in_progress` - A screenshot of a computer. + - `:completed` - - `detail: :low | :high | :auto | :original` + - `type: :apply_patch_call` - 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 item. Always `apply_patch_call`. - - `:low` + - `:apply_patch_call` - - `:high` + - `agent: Agent{ agent_name}` - - `:auto` + The agent that produced this item. - - `:original` + - `agent_name: String` - - `file_id: String` + The canonical name of the agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `image_url: String` + The execution context that produced this tool call. - The URL of the screenshot image. + - `class Direct` - - `type: :computer_screenshot` + - `type: :direct` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `:direct` - - `:computer_screenshot` + - `class Program` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + - `:program` - - `:explicit` + - `created_by: String` - - `class BetaResponseInputFile` + The ID of the entity that created this tool call. - A file input to the model. + - `class BetaResponseApplyPatchToolCallOutput` - - `class EncryptedContent` + The output emitted by an apply patch tool call. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `id: String` - - `encrypted_content: String` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Opaque encrypted content. + - `call_id: String` - - `type: :encrypted_content` + The unique ID of the apply patch tool call generated by the model. - The type of the input item. Always `encrypted_content`. + - `status: :completed | :failed` - - `:encrypted_content` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `recipient: String` + - `:completed` - The destination agent identity. + - `:failed` - - `type: :agent_message` + - `type: :apply_patch_call_output` - The type of the item. Always `agent_message`. + The type of the item. Always `apply_patch_call_output`. - - `:agent_message` + - `:apply_patch_call_output` - `agent: Agent{ agent_name}` @@ -91683,167 +103090,170 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCall` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the multi-agent call item. + - `class Direct` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :direct` - The multi-agent action to execute. + - `:direct` - - `:spawn_agent` + - `class Program` - - `:interrupt_agent` + - `caller_id: String` - - `:list_agents` + The call ID of the program item that produced this tool call. - - `:send_message` + - `type: :program` - - `:followup_task` + - `:program` - - `:wait_agent` + - `created_by: String` - - `arguments: String` + The ID of the entity that created this tool call output. - The JSON string of arguments generated for the action. + - `output: String` - - `call_id: String` + Optional textual output returned by the apply patch tool. - The unique ID linking this call to its output. + - `class McpCall` - - `type: :multi_agent_call` + An invocation of a tool on an MCP server. - The type of the multi-agent call. Always `multi_agent_call`. + - `id: String` - - `:multi_agent_call` + The unique ID of the tool call. - - `agent: Agent{ agent_name}` + - `arguments: String` - The agent that produced this item. + A JSON string of the arguments passed to the tool. - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the tool that was run. - - `class MultiAgentCallOutput` + - `server_label: String` - - `id: String` + The label of the MCP server running the tool. - The unique ID of the multi-agent call output item. + - `type: :mcp_call` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The type of the item. Always `mcp_call`. - The multi-agent action that produced this result. + - `:mcp_call` - - `:spawn_agent` + - `agent: Agent{ agent_name}` - - `:interrupt_agent` + The agent that produced this item. - - `:list_agents` + - `agent_name: String` - - `:send_message` + The canonical name of the agent that produced this item. - - `:followup_task` + - `approval_request_id: String` - - `:wait_agent` + 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. - - `call_id: String` + - `error: String` - The unique ID of the multi-agent call. + The error from the tool call, if any. - - `output: Array[BetaResponseOutputText]` + - `output: String` - Text output returned by the multi-agent action. + The output from the tool call. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `status: :in_progress | :completed | :incomplete | 2 more` - The annotations of the text output. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `text: String` + - `:in_progress` - The text output from the model. + - `:completed` - - `type: :output_text` + - `:incomplete` - The type of the output text. Always `output_text`. + - `:calling` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:failed` - - `type: :multi_agent_call_output` + - `class McpListTools` - The type of the multi-agent result. Always `multi_agent_call_output`. + A list of tools available on an MCP server. - - `:multi_agent_call_output` + - `id: String` - - `agent: Agent{ agent_name}` + The unique ID of the list. - The agent that produced this item. + - `server_label: String` - - `agent_name: String` + The label of the MCP server. - The canonical name of the agent that produced this item. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `class BetaResponseFunctionWebSearch` + The tools available on the server. - 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. + - `input_schema: untyped` - - `class BetaResponseComputerToolCall` + The JSON schema describing the tool's input. - 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. + - `name: String` - - `class BetaResponseComputerToolCallOutputItem` + The name of the tool. - - `id: String` + - `annotations: untyped` - The unique ID of the computer call tool output. + Additional annotations about the tool. - - `call_id: String` + - `description: String` - The ID of the computer tool call that produced the output. + The description of the tool. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: :mcp_list_tools` - A computer screenshot image used with the computer use tool. + The type of the item. Always `mcp_list_tools`. - - `status: :completed | :incomplete | :failed | :in_progress` + - `:mcp_list_tools` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `agent: Agent{ agent_name}` - - `:completed` + The agent that produced this item. - - `:incomplete` + - `agent_name: String` - - `:failed` + The canonical name of the agent that produced this item. - - `:in_progress` + - `error: String` - - `type: :computer_call_output` + Error message if the server could not list tools. - The type of the computer tool call output. Always `computer_call_output`. + - `class McpApprovalRequest` - - `:computer_call_output` + A request for human approval of a tool invocation. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `id: String` - The safety checks reported by the API that have been acknowledged by the - developer. + The unique ID of the approval request. - - `id: String` + - `arguments: String` - The ID of the pending safety check. + A JSON string of arguments for the tool. - - `code: String` + - `name: String` - The type of the pending safety check. + The name of the tool to run. - - `message: String` + - `server_label: String` - Details about the pending safety check. + 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: Agent{ agent_name}` @@ -91853,40 +103263,27 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseReasoningItem` - - 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). + - `class McpApprovalResponse` - - `class Program` + A response to an MCP approval request. - `id: String` - The unique ID of the program item. - - - `call_id: String` - - The stable call ID of the program item. + The unique ID of the approval response - - `code: String` + - `approval_request_id: String` - The JavaScript source executed by programmatic tool calling. + The ID of the approval request being answered. - - `fingerprint: String` + - `approve: bool` - Opaque program replay fingerprint that must be round-tripped. + Whether the request was approved. - - `type: :program` + - `type: :mcp_approval_response` - The type of the item. Always `program`. + The type of the item. Always `mcp_approval_response`. - - `:program` + - `:mcp_approval_response` - `agent: Agent{ agent_name}` @@ -91896,33 +103293,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput` + - `reason: String` - - `id: String` + Optional reason for the decision. - The unique ID of the program output item. + - `class BetaResponseCustomToolCall` + + A call to a custom tool created by the model. - `call_id: String` - The call ID of the program item. + An identifier used to map this custom tool call to a tool call output. - - `result: String` + - `input: String` - The result produced by the program item. + The input for the custom tool call generated by the model. - - `status: :completed | :incomplete` + - `name: String` - The terminal status of the program output item. + The name of the custom tool being called. - - `:completed` + - `type: :custom_tool_call` - - `:incomplete` + The type of the custom tool call. Always `custom_tool_call`. - - `type: :program_output` + - `:custom_tool_call` - The type of the item. Always `program_output`. + - `id: String` - - `:program_output` + The unique ID of the custom tool call in the OpenAI platform. - `agent: Agent{ agent_name}` @@ -91932,31 +103331,42 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the tool search call item. + - `class Direct` - - `arguments: untyped` + - `type: :direct` - Arguments used for the tool search call. + - `:direct` - - `call_id: String` + - `class Program` - The unique ID of the tool search call generated by the model. + - `caller_id: String` - - `execution: :server | :client` + The call ID of the program item that produced this tool call. - Whether tool search was executed by the server or by the client. + - `type: :program` - - `:server` + - `:program` - - `:client` + - `namespace: String` + + The namespace of the custom tool being called. + + - `class BetaResponseCustomToolCallOutputItem` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: String` + + The unique ID of the custom tool call output item. - `status: :in_progress | :completed | :incomplete` - The status of the tool search call 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` @@ -91964,237 +103374,250 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :tool_search_call` - - The type of the item. Always `tool_search_call`. + - `created_by: String` - - `:tool_search_call` + The identifier of the actor that created the item. - - `agent: Agent{ agent_name}` +### Beta Response Output Item Added Event - The agent that produced this item. +- `class BetaResponseOutputItemAddedEvent` - - `agent_name: String` + Emitted when a new output item is added. - The canonical name of the agent that produced this item. + - `item: BetaResponseOutputItem` - - `created_by: String` + The output item that was added. - The identifier of the actor that created the item. + - `class BetaResponseOutputMessage` - - `class BetaResponseToolSearchOutputItem` + An output message from the model. - `id: String` - The unique ID of the tool search output item. + The unique ID of the output message. - - `call_id: String` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The unique ID of the tool search call generated by the model. + The content of the output message. - - `execution: :server | :client` + - `class BetaResponseOutputText` - Whether tool search was executed by the server or by the client. + A text output from the model. - - `:server` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:client` + The annotations of the text output. - - `status: :in_progress | :completed | :incomplete` + - `class FileCitation` - The status of the tool search output item that was recorded. + A citation to a file. - - `:in_progress` + - `file_id: String` - - `:completed` + The ID of the file. - - `:incomplete` + - `filename: String` - - `tools: Array[BetaTool]` + The filename of the file cited. - The loaded tool definitions returned by tool search. + - `index: Integer` - - `class BetaFunctionTool` + The index of the file in the list of files. - 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: :file_citation` - - `class BetaFileSearchTool` + The type of the file citation. Always `file_citation`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `:file_citation` - - `class BetaComputerTool` + - `class URLCitation` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A citation for a web resource used to generate a model response. - - `class BetaComputerUsePreviewTool` + - `end_index: Integer` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the last character of the URL citation in the message. - - `class BetaWebSearchTool` + - `start_index: Integer` - 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 index of the first character of the URL citation in the message. - - `class Mcp` + - `title: 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 title of the web resource. - - `class CodeInterpreter` + - `type: :url_citation` - A tool that runs Python code to help generate a response to a prompt. + The type of the URL citation. Always `url_citation`. - - `class ProgrammaticToolCalling` + - `:url_citation` - - `class ImageGeneration` + - `url: String` - A tool that generates images using the GPT image models. + The URL of the web resource. - - `class LocalShell` + - `class ContainerFileCitation` - A tool that allows the model to execute shell commands in a local environment. + A citation for a container file used to generate a model response. - - `class BetaFunctionShellTool` + - `container_id: String` - A tool that allows the model to execute shell commands. + The ID of the container file. - - `class BetaCustomTool` + - `end_index: Integer` - 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 index of the last character of the container file citation in the message. - - `class BetaNamespaceTool` + - `file_id: String` - Groups function/custom tools under a shared namespace. + The ID of the file. - - `class BetaToolSearchTool` + - `filename: String` - Hosted or BYOT tool search configuration for deferred tools. + The filename of the container file cited. - - `class BetaWebSearchPreviewTool` + - `start_index: Integer` - 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 first character of the container file citation in the message. - - `class BetaApplyPatchTool` + - `type: :container_file_citation` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the container file citation. Always `container_file_citation`. - - `type: :tool_search_output` + - `:container_file_citation` - The type of the item. Always `tool_search_output`. + - `class FilePath` - - `:tool_search_output` + A path to a file. - - `agent: Agent{ agent_name}` + - `file_id: String` - The agent that produced this item. + The ID of the file. - - `agent_name: String` + - `index: Integer` - The canonical name of the agent that produced this item. + The index of the file in the list of files. - - `created_by: String` + - `type: :file_path` - The identifier of the actor that created the item. + The type of the file path. Always `file_path`. - - `class AdditionalTools` + - `:file_path` - - `id: String` + - `text: String` - The unique ID of the additional tools item. + The text output from the model. - - `role: :unknown | :user | :assistant | 5 more` + - `type: :output_text` - The role that provided the additional tools. + The type of the output text. Always `output_text`. - - `:unknown` + - `:output_text` - - `:user` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` - - `:assistant` + - `class BetaResponseOutputRefusal` - - `:system` + A refusal from the model. - - `:critic` + - `refusal: String` - - `:discriminator` + The refusal explanation from the model. - - `:developer` + - `type: :refusal` - - `:tool` + The type of the refusal. Always `refusal`. - - `tools: Array[BetaTool]` + - `:refusal` - The additional tool definitions made available at this item. + - `role: :assistant` - - `class BetaFunctionTool` + The role of the output message. Always `assistant`. - 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). + - `:assistant` - - `class BetaFileSearchTool` + - `status: :in_progress | :completed | :incomplete` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class BetaComputerTool` + - `: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` - - `class BetaComputerUsePreviewTool` + - `:incomplete` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :message` - - `class BetaWebSearchTool` + The type of the output message. Always `message`. - 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). + - `:message` - - `class Mcp` + - `agent: Agent{ 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. - - `class CodeInterpreter` + - `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. - - `class ProgrammaticToolCalling` + - `phase: :commentary | :final_answer` - - `class ImageGeneration` + 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 tool that generates images using the GPT image models. + - `:commentary` - - `class LocalShell` + - `:final_answer` - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseFileSearchToolCall` - - `class BetaFunctionShellTool` + 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 tool that allows the model to execute shell commands. + - `id: String` - - `class BetaCustomTool` + The unique ID of the file search tool 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) + - `queries: Array[String]` - - `class BetaNamespaceTool` + The queries used to search for files. - Groups function/custom tools under a shared namespace. + - `status: :in_progress | :searching | :completed | 2 more` - - `class BetaToolSearchTool` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Hosted or BYOT tool search configuration for deferred tools. + - `:in_progress` - - `class BetaWebSearchPreviewTool` + - `:searching` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `:completed` - - `class BetaApplyPatchTool` + - `:incomplete` - Allows the assistant to create, delete, or update files using unified diffs. + - `:failed` - - `type: :additional_tools` + - `type: :file_search_call` - The type of the item. Always `additional_tools`. + The type of the file search tool call. Always `file_search_call`. - - `:additional_tools` + - `:file_search_call` - `agent: Agent{ agent_name}` @@ -92204,65 +103627,66 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `id: String` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - The unique ID of the compaction item. + The results of the file search tool call. - - `encrypted_content: String` + - `attributes: Hash[Symbol, String | Float | bool]` - The encrypted content that was produced by compaction. + Set of 16 key-value pairs that can be attached to an object. 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: :compaction` + - `String = String` - The type of the item. Always `compaction`. + - `Float = Float` - - `:compaction` + - `UnionMember2 = bool` - - `agent: Agent{ agent_name}` + - `file_id: String` - The agent that produced this item. + The unique ID of the file. - - `agent_name: String` + - `filename: String` - The canonical name of the agent that produced this item. + The name of the file. - - `created_by: String` + - `score: Float` - The identifier of the actor that created the item. + The relevance score of the file - a value between 0 and 1. - - `class ImageGenerationCall` + - `text: String` - An image generation request made by the model. + The text that was retrieved from the file. - - `id: String` + - `class BetaResponseFunctionToolCall` - The unique ID of the image generation call. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `result: String` + - `arguments: String` - The generated image encoded in base64. + A JSON string of the arguments to pass to the function. - - `status: :in_progress | :completed | :generating | :failed` + - `call_id: String` - The status of the image generation call. + The unique ID of the function tool call generated by the model. - - `:in_progress` + - `name: String` - - `:completed` + The name of the function to run. - - `:generating` + - `type: :function_call` - - `:failed` + The type of the function tool call. Always `function_call`. - - `type: :image_generation_call` + - `:function_call` - The type of the image generation call. Always `image_generation_call`. + - `id: String` - - `:image_generation_call` + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -92272,167 +103696,178 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` - - A tool call to run code. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class LocalShellCall` + The execution context that produced this tool call. - A tool call to run a command on the local shell. + - `class Direct` - - `id: String` + - `type: :direct` - The unique ID of the local shell call. + - `:direct` - - `action: Action{ command, env, type, 3 more}` + - `class Program` - Execute a shell command on the server. + - `caller_id: String` - - `command: Array[String]` + The call ID of the program item that produced this tool call. - The command to run. + - `type: :program` - - `env: Hash[Symbol, String]` + - `:program` - Environment variables to set for the command. + - `namespace: String` - - `type: :exec` + The namespace of the function to run. - The type of the local shell action. Always `exec`. + - `status: :in_progress | :completed | :incomplete` - - `:exec` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `timeout_ms: Integer` + - `:in_progress` - Optional timeout in milliseconds for the command. + - `:completed` - - `user: String` + - `:incomplete` - Optional user to run the command as. + - `class BetaResponseFunctionToolCallOutputItem` - - `working_directory: String` + - `id: String` - Optional working directory to run the command in. + The unique ID of the function call tool output. - `call_id: String` - The unique ID of the local shell tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `status: :in_progress | :completed | :incomplete` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The status of the local shell call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:in_progress` + - `String = String` - - `:completed` + A string of the output of the function call. - - `:incomplete` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `type: :local_shell_call` + Text, image, or file output of the function call. - The type of the local shell call. Always `local_shell_call`. + - `class BetaResponseInputText` - - `:local_shell_call` + A text input to the model. - - `agent: Agent{ 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`. - - `class LocalShellCallOutput` + - `:input_text` - The output of a local shell tool call. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 local shell tool call generated by the model. + - `mode: :explicit` - - `output: String` + The breakpoint mode. Always `explicit`. - A JSON string of the output of the local shell tool call. + - `:explicit` - - `type: :local_shell_call_output` + - `class BetaResponseInputImage` - The type of the local shell tool call output. Always `local_shell_call_output`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:local_shell_call_output` + - `detail: :low | :high | :auto | :original` - - `agent: Agent{ agent_name}` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The agent that produced this item. + - `:low` - - `agent_name: String` + - `:high` - The canonical name of the agent that produced this item. + - `:auto` - - `status: :in_progress | :completed | :incomplete` + - `:original` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `type: :input_image` - - `:in_progress` + The type of the input item. Always `input_image`. - - `:completed` + - `:input_image` - - `:incomplete` + - `file_id: String` - - `class BetaResponseFunctionShellToolCall` + The ID of the file to be sent to the model. - A tool call that executes one or more shell commands in a managed environment. + - `image_url: String` - - `id: String` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `action: Action{ commands, max_output_length, timeout_ms}` + Marks the exact end of a reusable 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 shell commands and limits that describe how to run the tool call. + - `mode: :explicit` - - `commands: Array[String]` + The breakpoint mode. Always `explicit`. - - `max_output_length: Integer` + - `:explicit` - Optional maximum number of characters to return from each command. + - `class BetaResponseInputFile` - - `timeout_ms: Integer` + A file input to the model. - Optional timeout in milliseconds for the commands. + - `type: :input_file` - - `call_id: String` + The type of the input item. Always `input_file`. - The unique ID of the shell tool call generated by the model. + - `:input_file` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `detail: :auto | :low | :high` - Represents the use of a local environment to perform shell actions. + 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`. - - `class BetaResponseLocalEnvironment` + - `:auto` - Represents the use of a local environment to perform shell actions. + - `:low` - - `type: :local` + - `:high` - The environment type. Always `local`. + - `file_data: String` - - `:local` + The content of the file to be sent to the model. - - `class BetaResponseContainerReference` + - `file_id: String` - Represents a container created with /v1/containers. + The ID of the file to be sent to the model. - - `container_id: String` + - `file_url: String` - - `type: :container_reference` + The URL of the file to be sent to the model. - The environment type. Always `container_reference`. + - `filename: String` - - `:container_reference` + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 | :completed | :incomplete` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -92440,11 +103875,11 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :shell_call` + - `type: :function_call_output` - The type of the item. Always `shell_call`. + The type of the function tool call output. Always `function_call_output`. - - `:shell_call` + - `:function_call_output` - `agent: Agent{ agent_name}` @@ -92462,6 +103897,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -92472,199 +103909,193 @@ puts(beta_compacted_response) - `type: :program` + The caller type. Always `program`. + - `:program` - `created_by: String` - The ID of the entity that created this tool call. - - - `class BetaResponseFunctionShellToolCallOutput` + The identifier of the actor that created the item. - The output of a shell tool call that was emitted. + - `class AgentMessage` - `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: Integer` + The unique ID of the agent message. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `author: String` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + The sending agent identity. - An array of shell call output contents + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + Encrypted content sent between agents. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `class BetaResponseInputText` - - `class Timeout` + A text input to the model. - Indicates that the shell call exceeded its configured time limit. + - `class BetaResponseOutputText` - - `type: :timeout` + A text output from the model. - The outcome type. Always `timeout`. + - `class Text` - - `:timeout` + A text content. - - `class Exit` + - `text: String` - Indicates that the shell commands finished and returned an exit code. + - `type: :text` - - `exit_code: Integer` + - `:text` - Exit code from the shell process. + - `class SummaryText` - - `type: :exit` + A summary text from the model. - The outcome type. Always `exit`. + - `text: String` - - `:exit` + A summary of the reasoning output from the model so far. - - `stderr: String` + - `type: :summary_text` - The standard error output that was captured. + The type of the object. Always `summary_text`. - - `stdout: String` + - `:summary_text` - The standard output that was captured. + - `class ReasoningText` - - `created_by: String` + Reasoning text from the model. - The identifier of the actor that created the item. + - `text: String` - - `status: :in_progress | :completed | :incomplete` + The reasoning text from the model. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `type: :reasoning_text` - - `:in_progress` + The type of the reasoning text. Always `reasoning_text`. - - `:completed` + - `:reasoning_text` - - `:incomplete` + - `class BetaResponseOutputRefusal` - - `type: :shell_call_output` + A refusal from the model. - The type of the shell call output. Always `shell_call_output`. + - `class BetaResponseInputImage` - - `:shell_call_output` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `agent: Agent{ agent_name}` + - `class ComputerScreenshot` - The agent that produced this item. + A screenshot of a computer. - - `agent_name: String` + - `detail: :low | :high | :auto | :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`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:low` - The execution context that produced this tool call. + - `:high` - - `class Direct` + - `:auto` - - `type: :direct` + - `:original` - - `:direct` + - `file_id: String` - - `class Program` + The identifier of an uploaded file that contains the screenshot. - - `caller_id: String` + - `image_url: String` - The call ID of the program item that produced this tool call. + The URL of the screenshot image. - - `type: :program` + - `type: :computer_screenshot` - - `:program` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `created_by: String` + - `:computer_screenshot` - The identifier of the actor that created the item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class BetaResponseApplyPatchToolCall` + Marks the exact end of a reusable 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 that applies file diffs by creating, deleting, or updating files. + - `mode: :explicit` - - `id: String` + The breakpoint mode. Always `explicit`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `:explicit` - - `call_id: String` + - `class BetaResponseInputFile` - The unique ID of the apply patch tool call generated by the model. + A file input to the model. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `class EncryptedContent` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `class CreateFile` + - `encrypted_content: String` - Instruction describing how to create a file via the apply_patch tool. + Opaque encrypted content. - - `diff: String` + - `type: :encrypted_content` - Diff to apply. + The type of the input item. Always `encrypted_content`. - - `path: String` + - `:encrypted_content` - Path of the file to create. + - `recipient: String` - - `type: :create_file` + The destination agent identity. - Create a new file with the provided diff. + - `type: :agent_message` - - `:create_file` + The type of the item. Always `agent_message`. - - `class DeleteFile` + - `:agent_message` - Instruction describing how to delete a file via the apply_patch tool. + - `agent: Agent{ agent_name}` - - `path: String` + The agent that produced this item. - Path of the file to delete. + - `agent_name: String` - - `type: :delete_file` + The canonical name of the agent that produced this item. - Delete the specified file. + - `class MultiAgentCall` - - `:delete_file` + - `id: String` - - `class UpdateFile` + The unique ID of the multi-agent call item. - Instruction describing how to update a file via the apply_patch tool. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `diff: String` + The multi-agent action to execute. - Diff to apply. + - `:spawn_agent` - - `path: String` + - `:interrupt_agent` - Path of the file to update. + - `:list_agents` - - `type: :update_file` + - `:send_message` - Update an existing file with the provided diff. + - `:followup_task` - - `:update_file` + - `:wait_agent` - - `status: :in_progress | :completed` + - `arguments: String` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The JSON string of arguments generated for the action. - - `:in_progress` + - `call_id: String` - - `:completed` + The unique ID linking this call to its output. - - `type: :apply_patch_call` + - `type: :multi_agent_call` - The type of the item. Always `apply_patch_call`. + The type of the multi-agent call. Always `multi_agent_call`. - - `:apply_patch_call` + - `:multi_agent_call` - `agent: Agent{ agent_name}` @@ -92674,55 +104105,55 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class MultiAgentCallOutput` - The execution context that produced this tool call. + - `id: String` - - `class Direct` + The unique ID of the multi-agent call output item. - - `type: :direct` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:direct` + The multi-agent action that produced this result. - - `class Program` + - `: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` - - `created_by: String` + - `:wait_agent` - The ID of the entity that created this tool call. + - `call_id: String` - - `class BetaResponseApplyPatchToolCallOutput` + The unique ID of the multi-agent call. - The output emitted by an apply patch tool call. + - `output: Array[BetaResponseOutputText]` - - `id: String` + Text output returned by the multi-agent action. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `call_id: String` + The annotations of the text output. - The unique ID of the apply patch tool call generated by the model. + - `text: String` - - `status: :completed | :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` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `type: :apply_patch_call_output` + - `type: :multi_agent_call_output` - The type of the item. Always `apply_patch_call_output`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `:apply_patch_call_output` + - `:multi_agent_call_output` - `agent: Agent{ agent_name}` @@ -92732,59 +104163,101 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseFunctionWebSearch` - The execution context that produced this tool call. + 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. - - `class Direct` + - `id: String` - - `type: :direct` + The unique ID of the web search tool call. - - `:direct` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `class 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). - - `caller_id: String` + - `class Search` - The call ID of the program item that produced this tool call. + Action type "search" - Performs a web search query. - - `type: :program` + - `type: :search` - - `:program` + The action type. - - `created_by: String` + - `:search` - The ID of the entity that created this tool call output. + - `queries: Array[String]` - - `output: String` + The search queries. - Optional textual output returned by the apply patch tool. + - `query: String` - - `class McpCall` + The search query. - An invocation of a tool on an MCP server. + - `sources: Array[Source{ type, url}]` - - `id: String` + The sources used in the search. - The unique ID of the tool call. + - `type: :url` - - `arguments: String` + The type of source. Always `url`. - A JSON string of the arguments passed to the tool. + - `:url` - - `name: String` + - `url: String` - The name of the tool that was run. + The URL of the source. - - `server_label: String` + - `class OpenPage` - The label of the MCP server running the tool. + Action type "open_page" - Opens a specific URL from search results. - - `type: :mcp_call` + - `type: :open_page` - The type of the item. Always `mcp_call`. + The action type. - - `:mcp_call` + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + 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 | :searching | :completed | :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: Agent{ agent_name}` @@ -92794,22 +104267,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `approval_request_id: String` + - `class BetaResponseComputerToolCall` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `error: String` + - `id: String` - The error from the tool call, if any. + The unique ID of the computer call. - - `output: String` + - `call_id: String` - The output from the tool call. + An identifier used when responding to the tool call with output. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -92817,867 +104307,837 @@ puts(beta_compacted_response) - `:incomplete` - - `:calling` + - `type: :computer_call` - - `:failed` + The type of the computer call. Always `computer_call`. - - `class McpListTools` + - `:computer_call` - A list of tools available on an MCP server. + - `action: BetaComputerAction` - - `id: String` + A click action. - The unique ID of the list. + - `class Click` - - `server_label: String` + A click action. - The label of the MCP server. + - `button: :left | :right | :wheel | 2 more` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The tools available on the server. + - `:left` - - `input_schema: untyped` + - `:right` - The JSON schema describing the tool's input. + - `:wheel` - - `name: String` + - `:back` - The name of the tool. + - `:forward` - - `annotations: untyped` + - `type: :click` - Additional annotations about the tool. + Specifies the event type. For a click action, this property is always `click`. - - `description: String` + - `:click` - The description of the tool. + - `x: Integer` - - `type: :mcp_list_tools` + The x-coordinate where the click occurred. - The type of the item. Always `mcp_list_tools`. + - `y_: Integer` - - `:mcp_list_tools` + The y-coordinate where the click occurred. - - `agent: Agent{ agent_name}` + - `keys: Array[String]` - The agent that produced this item. + The keys being held while clicking. - - `agent_name: String` + - `class DoubleClick` - The canonical name of the agent that produced this item. + A double click action. - - `error: String` + - `keys: Array[String]` - Error message if the server could not list tools. + The keys being held while double-clicking. - - `class McpApprovalRequest` + - `type: :double_click` - A request for human approval of a tool invocation. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `id: String` + - `:double_click` - The unique ID of the approval request. + - `x: Integer` - - `arguments: String` + The x-coordinate where the double click occurred. - A JSON string of arguments for the tool. + - `y_: Integer` - - `name: String` + The y-coordinate where the double click occurred. - The name of the tool to run. + - `class Drag` - - `server_label: String` + A drag action. - The label of the MCP server making the request. + - `path: Array[Path{ x, y_}]` - - `type: :mcp_approval_request` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The type of the item. Always `mcp_approval_request`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `:mcp_approval_request` + - `x: Integer` - - `agent: Agent{ agent_name}` + The x-coordinate. - The agent that produced this item. + - `y_: Integer` - - `agent_name: String` + The y-coordinate. - The canonical name of the agent that produced this item. + - `type: :drag` - - `class McpApprovalResponse` + Specifies the event type. For a drag action, this property is always set to `drag`. - A response to an MCP approval request. + - `:drag` - - `id: String` + - `keys: Array[String]` - The unique ID of the approval response + The keys being held while dragging the mouse. - - `approval_request_id: String` + - `class Keypress` - The ID of the approval request being answered. + A collection of keypresses the model would like to perform. - - `approve: bool` + - `keys: Array[String]` - Whether the request was approved. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `type: :mcp_approval_response` + - `type: :keypress` - The type of the item. Always `mcp_approval_response`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `:mcp_approval_response` + - `:keypress` - - `agent: Agent{ agent_name}` + - `class Move` - The agent that produced this item. + A mouse move action. - - `agent_name: String` + - `type: :move` - The canonical name of the agent that produced this item. + Specifies the event type. For a move action, this property is always set to `move`. - - `reason: String` + - `:move` - Optional reason for the decision. + - `x: Integer` - - `class BetaResponseCustomToolCall` + The x-coordinate to move to. - A call to a custom tool created by the model. + - `y_: Integer` - - `class BetaResponseCustomToolCallOutputItem` + The y-coordinate to move to. - The output of a custom tool call from your code, being sent back to the model. + - `keys: Array[String]` - - `id: String` + The keys being held while moving the mouse. - The unique ID of the custom tool call output item. + - `class Screenshot` - - `status: :in_progress | :completed | :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` + - `class Scroll` - - `created_by: String` + A scroll action. - The identifier of the actor that created the item. + - `scroll_x: Integer` - - `parallel_tool_calls: bool` + The horizontal scroll distance. - Whether to allow the model to run tool calls in parallel. + - `scroll_y: Integer` - - `temperature: Float` + The vertical scroll distance. - 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: :scroll` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - 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. + - `:scroll` - - `BetaToolChoiceOptions = :none | :auto | :required` + - `x: Integer` - Controls which (if any) tool is called by the model. + The x-coordinate where the scroll occurred. - `none` means the model will not call any tool and instead generates a message. + - `y_: Integer` - `auto` means the model can pick between generating a message or calling one or - more tools. + The y-coordinate where the scroll occurred. - `required` means the model must call one or more tools. + - `keys: Array[String]` - - `:none` + The keys being held while scrolling. - - `:auto` + - `class Type` - - `:required` + An action to type in text. - - `class BetaToolChoiceAllowed` + - `text: String` - Constrains the tools available to the model to a pre-defined set. + The text to type. - - `mode: :auto | :required` + - `type: :type` - Constrains the tools available to the model to a pre-defined set. + Specifies the event type. For a type action, this property is always set to `type`. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `:type` - `required` requires the model to call one or more of the allowed tools. + - `class Wait` - - `:auto` + A wait action. - - `:required` + - `type: :wait` - - `tools: Array[Hash[Symbol, untyped]]` + Specifies the event type. For a wait action, this property is always set to `wait`. - A list of tool definitions that the model should be allowed to call. + - `:wait` - For the Responses API, the list of tool definitions might look like: + - `actions: BetaComputerActionList` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: :allowed_tools` + - `class Click` - Allowed tool configuration type. Always `allowed_tools`. + A click action. - - `:allowed_tools` + - `class DoubleClick` - - `class BetaToolChoiceTypes` + A double click action. - 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). + - `class Drag` - - `type: :file_search | :web_search_preview | :computer | 5 more` + A drag action. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `class Keypress` - Allowed values are: + A collection of keypresses the model would like to perform. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `class Move` - - `:file_search` + A mouse move action. - - `:web_search_preview` + - `class Screenshot` - - `:computer` + A screenshot action. - - `:computer_use_preview` + - `class Scroll` - - `:computer_use` + A scroll action. - - `:web_search_preview_2025_03_11` + - `class Type` - - `:image_generation` + An action to type in text. - - `:code_interpreter` + - `class Wait` - - `class BetaToolChoiceFunction` + A wait action. - Use this option to force the model to call a specific function. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the function to call. + - `agent_name: String` - - `type: :function` + The canonical name of the agent that produced this item. - For function calling, the type is always `function`. + - `class BetaResponseComputerToolCallOutputItem` - - `:function` + - `id: String` - - `class BetaToolChoiceMcp` + The unique ID of the computer call tool output. - Use this option to force the model to call a specific tool on a remote MCP server. + - `call_id: String` - - `server_label: String` + The ID of the computer tool call that produced the output. - The label of the MCP server to use. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `type: :mcp` + A computer screenshot image used with the computer use tool. - For MCP tools, the type is always `mcp`. + - `type: :computer_screenshot` - - `:mcp` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `name: String` + - `:computer_screenshot` - The name of the tool to call on the server. + - `file_id: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: String` + + The URL of the screenshot image. + + - `status: :completed | :incomplete | :failed | :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: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `class BetaToolChoiceCustom` + The safety checks reported by the API that have been acknowledged by the + developer. - Use this option to force the model to call a specific custom tool. + - `id: String` - - `name: String` + The ID of the pending safety check. - The name of the custom tool to call. + - `code: String` - - `type: :custom` + The type of the pending safety check. - For custom tool calling, the type is always `custom`. + - `message: String` - - `:custom` + Details about the pending safety check. - - `class BetaSpecificProgrammaticToolCallingParam` + - `agent: Agent{ 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. - - `class BetaToolChoiceApplyPatch` + - `created_by: String` - Forces the model to call the apply_patch tool when executing a tool call. + The identifier of the actor that created the item. - - `type: :apply_patch` + - `class BetaResponseReasoningItem` - The tool to call. Always `apply_patch`. + 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). - - `:apply_patch` + - `id: String` - - `class BetaToolChoiceShell` + The unique identifier of the reasoning content. - Forces the model to call the shell tool when a tool call is required. + - `summary: Array[Summary{ text, type}]` - - `type: :shell` + Reasoning summary content. - The tool to call. Always `shell`. + - `text: String` - - `:shell` + A summary of the reasoning output from the model so far. - - `tools: Array[BetaTool]` + - `type: :summary_text` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The type of the object. Always `summary_text`. - We support the following categories of tools: + - `:summary_text` - - **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. + - `type: :reasoning` - - `class BetaFunctionTool` + The type of the object. Always `reasoning`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `:reasoning` - - `class BetaFileSearchTool` + - `agent: Agent{ 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. - - `class BetaComputerTool` + - `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. - - `class BetaComputerUsePreviewTool` + - `content: Array[Content{ text, type}]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Reasoning text content. - - `class BetaWebSearchTool` + - `text: 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 reasoning text from the model. - - `class Mcp` + - `type: :reasoning_text` - 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 type of the reasoning text. Always `reasoning_text`. - - `class CodeInterpreter` + - `:reasoning_text` - A tool that runs Python code to help generate a response to a prompt. + - `encrypted_content: String` - - `class ProgrammaticToolCalling` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `class ImageGeneration` + - `status: :in_progress | :completed | :incomplete` - A tool that generates images using the GPT image models. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class LocalShell` + - `:in_progress` - A tool that allows the model to execute shell commands in a local environment. + - `:completed` - - `class BetaFunctionShellTool` + - `:incomplete` - A tool that allows the model to execute shell commands. + - `class Program` - - `class BetaCustomTool` + - `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 program item. - - `class BetaNamespaceTool` + - `call_id: String` - Groups function/custom tools under a shared namespace. + The stable call ID of the program item. - - `class BetaToolSearchTool` + - `code: String` - Hosted or BYOT tool search configuration for deferred tools. + The JavaScript source executed by programmatic tool calling. - - `class BetaWebSearchPreviewTool` + - `fingerprint: 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). + Opaque program replay fingerprint that must be round-tripped. - - `class BetaApplyPatchTool` + - `type: :program` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the item. Always `program`. - - `top_p: Float` + - `: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. + - `agent: Agent{ agent_name}` - We generally recommend altering this or `temperature` but not both. + The agent that produced this item. - - `background: bool` + - `agent_name: String` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The canonical name of the agent that produced this item. - - `completed_at: Float` + - `class ProgramOutput` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `id: String` - - `conversation: Conversation{ id}` + The unique ID of the program output item. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `call_id: String` - - `id: String` + The call ID of the program item. - The unique ID of the conversation that this response was associated with. + - `result: String` - - `max_output_tokens: Integer` + The result produced by the program 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). + - `status: :completed | :incomplete` - - `max_tool_calls: Integer` + The terminal status of the program output 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. + - `:completed` - - `moderation: Moderation{ input, output}` + - `:incomplete` - Moderation results for the response input and output, if moderated completions were requested. + - `type: :program_output` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + The type of the item. Always `program_output`. - Moderation for the response input. + - `:program_output` - - `class ModerationResult` + - `agent: Agent{ agent_name}` - A moderation result produced for the response input or output. + The agent that produced this item. - - `categories: Hash[Symbol, bool]` + - `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: Hash[Symbol, Array[:text | :image]]` + - `class BetaResponseToolSearchCall` - Which modalities of input are reflected by the score for each category. + - `id: String` - - `:text` + The unique ID of the tool search call item. - - `:image` + - `arguments: untyped` - - `category_scores: Hash[Symbol, Float]` + Arguments used for the tool search call. - A dictionary of moderation categories to scores. + - `call_id: String` - - `flagged: bool` + The unique ID of the tool search call generated by the model. - A boolean indicating whether the content was flagged by any category. + - `execution: :server | :client` - - `model: String` + Whether tool search was executed by the server or by the client. - The moderation model that produced this result. + - `:server` - - `type: :moderation_result` + - `:client` - The object type, which was always `moderation_result` for successful moderation results. + - `status: :in_progress | :completed | :incomplete` - - `:moderation_result` + The status of the tool search call item that was recorded. - - `class Error` + - `:in_progress` - An error produced while attempting moderation for the response input or output. + - `:completed` - - `code: String` + - `:incomplete` - The error code. + - `type: :tool_search_call` - - `message: String` + The type of the item. Always `tool_search_call`. - The error message. + - `:tool_search_call` - - `type: :error` + - `agent: Agent{ agent_name}` - The object type, which was always `error` for moderation failures. + The agent that produced this item. - - `:error` + - `agent_name: String` - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + The canonical name of the agent that produced this item. - Moderation for the response output. + - `created_by: String` - - `class ModerationResult` + The identifier of the actor that created the item. - A moderation result produced for the response input or output. + - `class BetaResponseToolSearchOutputItem` - - `categories: Hash[Symbol, bool]` + - `id: String` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The unique ID of the tool search output item. - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `call_id: String` - Which modalities of input are reflected by the score for each category. + The unique ID of the tool search call generated by the model. - - `:text` + - `execution: :server | :client` - - `:image` + Whether tool search was executed by the server or by the client. - - `category_scores: Hash[Symbol, Float]` + - `:server` - A dictionary of moderation categories to scores. + - `:client` - - `flagged: bool` + - `status: :in_progress | :completed | :incomplete` - A boolean indicating whether the content was flagged by any category. + The status of the tool search output item that was recorded. - - `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. + - `tools: Array[BetaTool]` - - `:moderation_result` + The loaded tool definitions returned by tool search. - - `class Error` + - `class BetaFunctionTool` - An error produced while attempting moderation for the response input or 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). - - `code: String` + - `name: String` - The error code. + The name of the function to call. - - `message: String` + - `parameters: Hash[Symbol, untyped]` - The error message. + A JSON schema object describing the parameters of the function. - - `type: :error` + - `strict: bool` - The object type, which was always `error` for moderation failures. + Whether strict parameter validation is enforced for this function tool. - - `:error` + - `type: :function` - - `previous_response_id: String` + The type of the function tool. Always `function`. - 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`. + - `:function` - - `prompt: BetaResponsePrompt` + - `allowed_callers: Array[:direct | :programmatic]` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The tool invocation context(s). - - `id: String` + - `:direct` - The unique identifier of the prompt template to use. + - `:programmatic` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `defer_loading: bool` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Whether this function is deferred and loaded via tool search. - - `String = String` + - `description: String` - - `class BetaResponseInputText` + A description of the function. Used by the model to determine whether or not to call the function. - A text input to the model. + - `output_schema: Hash[Symbol, untyped]` - - `class BetaResponseInputImage` + A JSON schema object describing the JSON value encoded in string outputs for this function. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class BetaFileSearchTool` - - `class BetaResponseInputFile` + 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 file input to the model. + - `type: :file_search` - - `version: String` + The type of the file search tool. Always `file_search`. - Optional version of the prompt template. + - `:file_search` - - `prompt_cache_key: String` + - `vector_store_ids: Array[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 IDs of the vector stores to search. - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + A filter to apply. - - `mode: :implicit | :explicit` + - `class ComparisonFilter` - Whether implicit prompt-cache breakpoints were enabled. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:implicit` + - `key: String` - - `:explicit` + The key to compare against the value. - - `ttl: :"30m"` + - `type: :eq | :ne | :gt | 5 more` - The minimum lifetime applied to each cache breakpoint. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:"30m"` + - `eq`: equals + - `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_retention: :in_memory | :"24h"` + - `:eq` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `:ne` - 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. + - `:gt` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `:gte` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `:lt` - - `:in_memory` + - `:lte` - - `:"24h"` + - `:in` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `:nin` - **gpt-5 and o-series models only** + - `value: String | Float | bool | Array[String | Float]` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The value to compare against the attribute key; supports string, number, or boolean types. - - `context: :auto | :current_turn | :all_turns` + - `String = 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. + - `Float = Float` - - `:auto` + - `UnionMember2 = bool` - - `:current_turn` + - `UnionMember3 = Array[String | Float]` - - `:all_turns` + - `String = String` - - `effort: :none | :minimal | :low | 4 more` + - `Float = Float` - 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. + - `class CompoundFilter` - - `:none` + Combine multiple filters using `and` or `or`. - - `:minimal` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `:low` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `:medium` + - `class ComparisonFilter` - - `:high` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:xhigh` + - `key: String` - - `:max` + The key to compare against the value. - - `generate_summary: :auto | :concise | :detailed` + - `type: :eq | :ne | :gt | 5 more` - **Deprecated:** use `summary` instead. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `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`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `:auto` + - `:eq` - - `:concise` + - `:ne` - - `:detailed` + - `:gt` - - `mode: String | :standard | :pro` + - `:gte` - Controls the reasoning execution mode for the request. + - `:lt` - When returned on a response, this is the effective execution mode. + - `:lte` - - `String = String` + - `:in` - - `Mode = :standard | :pro` + - `:nin` - Controls the reasoning execution mode for the request. + - `value: String | Float | bool | Array[String | Float]` - When returned on a response, this is the effective execution mode. + The value to compare against the attribute key; supports string, number, or boolean types. - - `:standard` + - `String = String` - - `:pro` + - `Float = Float` - - `summary: :auto | :concise | :detailed` + - `UnionMember2 = bool` - 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`. + - `UnionMember3 = Array[String | Float]` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `String = String` - - `:auto` + - `Float = Float` - - `:concise` + - `UnionMember1 = untyped` - - `:detailed` + - `type: :and | :or` - - `safety_identifier: String` + Type of operation: `and` or `or`. - 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). + - `:and` - - `service_tier: :auto | :default | :flex | 2 more` + - `:or` - Specifies the processing type used for serving the request. + - `max_num_results: Integer` - - 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 number of results to return. This number should be between 1 and 50 inclusive. - 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. + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - - `:auto` + Ranking options for search. - - `:default` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `:flex` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `:scale` + - `embedding_weight: Float` - - `:priority` + The weight of the embedding in the reciprocal ranking fusion. - - `status: BetaResponseStatus` + - `text_weight: Float` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The weight of the text in the reciprocal ranking fusion. - - `:completed` + - `ranker: :auto | :"default-2024-11-15"` - - `:failed` + The ranker to use for the file search. - - `:in_progress` + - `:auto` - - `:cancelled` + - `:"default-2024-11-15"` - - `:queued` + - `score_threshold: Float` - - `: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. - - `text: BetaResponseTextConfig` + - `class BetaComputerTool` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `type: :computer` - - `format_: BetaResponseFormatTextConfig` + The type of the computer tool. Always `computer`. - An object specifying the format that the model must output. + - `:computer` - 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). + - `class BetaComputerUsePreviewTool` - The default format is `{ "type": "text" }` with no additional options. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - **Not recommended for gpt-4o and newer models:** + - `display_height: Integer` - 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 height of the computer display. - - `class Text` + - `display_width: Integer` - Default response format. Used to generate text responses. + The width of the computer display. - - `type: :text` + - `environment: :windows | :mac | :linux | 2 more` - The type of response format being defined. Always `text`. + The type of computer environment to control. - - `:text` + - `:windows` - - `class BetaResponseFormatTextJSONSchemaConfig` + - `:mac` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:linux` - - `name: String` + - `:ubuntu` - 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. + - `:browser` - - `schema: Hash[Symbol, untyped]` + - `type: :computer_use_preview` - 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 computer use tool. Always `computer_use_preview`. - - `type: :json_schema` + - `:computer_use_preview` - The type of response format being defined. Always `json_schema`. + - `class BetaWebSearchTool` - - `:json_schema` + 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). - - `description: String` + - `type: :web_search | :web_search_2025_08_26` - 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 web search tool. One of `web_search` or `web_search_2025_08_26`. - - `strict: bool` + - `:web_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](https://platform.openai.com/docs/guides/structured-outputs). + - `:web_search_2025_08_26` - - `class JSONObject` + - `filters: Filters{ allowed_domains}` - 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. + Filters for the search. - - `type: :json_object` + - `allowed_domains: Array[String]` - The type of response format being defined. Always `json_object`. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `:json_object` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `verbosity: :low | :medium | :high` + - `search_context_size: :low | :medium | :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`. + High 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` @@ -93685,914 +105145,925 @@ puts(beta_compacted_response) - `:high` - - `top_logprobs: Integer` + - `user_location: UserLocation{ city, country, region, 2 more}` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The approximate location of the user. - - `truncation: :auto | :disabled` + - `city: String` - The truncation strategy to use for the model response. + Free text input for the city of the user, e.g. `San Francisco`. - - `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. + - `country: String` - - `:auto` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `:disabled` + - `region: String` - - `usage: BetaResponseUsage` + Free text input for the region of the user, e.g. `California`. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `timezone: String` - - `input_tokens: Integer` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The number of input tokens. + - `type: :approximate` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + The type of location approximation. Always `approximate`. - A detailed breakdown of the input tokens. + - `:approximate` - - `cache_write_tokens: Integer` + - `class Mcp` - The number of input tokens that were written to the cache. + 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). - - `cached_tokens: Integer` + - `server_label: String` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + A label for this MCP server, used to identify it in tool calls. - - `output_tokens: Integer` + - `type: :mcp` - The number of output tokens. + The type of the MCP tool. Always `mcp`. - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `:mcp` - A detailed breakdown of the output tokens. + - `allowed_callers: Array[:direct | :programmatic]` - - `reasoning_tokens: Integer` + The tool invocation context(s). - The number of reasoning tokens. + - `:direct` - - `total_tokens: Integer` + - `:programmatic` - The total number of tokens used. + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `user: String` + List of allowed tool names or a filter object. - 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). + - `McpAllowedTools = Array[String]` - - `sequence_number: Integer` + A string array of allowed tool names - The sequence number of this event. + - `class McpToolFilter` - - `type: :"response.incomplete"` + A filter object to specify which tools are allowed. - The type of the event. Always `response.incomplete`. + - `read_only: bool` - - `:"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. - - `agent: Agent{ agent_name}` + - `tool_names: Array[String]` - The agent that owns this multi-agent streaming event. + List of allowed tool names. - - `agent_name: String` + - `authorization: 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. -### Beta Response Input + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` -- `BetaResponseInput = Array[BetaResponseInputItem]` + 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 list of one or many input items to the model, containing - different content types. + Currently supported `connector_id` values are: - - `class BetaEasyInputMessage` + - 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 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_dropbox` - - `content: String | BetaResponseInputMessageContentList` + - `:connector_gmail` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `:connector_googlecalendar` - - `String = String` + - `:connector_googledrive` - A text input to the model. + - `:connector_microsoftteams` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `:connector_outlookcalendar` - A list of one or many input items to the model, containing different content - types. + - `:connector_outlookemail` - - `class BetaResponseInputText` + - `:connector_sharepoint` - A text input to the model. + - `defer_loading: bool` - - `text: String` + Whether this MCP tool is deferred and discovered via tool search. - The text input to the model. + - `headers: Hash[Symbol, String]` - - `type: :input_text` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The type of the input item. Always `input_text`. + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `:input_text` + Specify which of the MCP server's tools require approval. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class McpToolApprovalFilter` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `mode: :explicit` + - `always: Always{ read_only, tool_names}` - The breakpoint mode. Always `explicit`. + A filter object to specify which tools are allowed. - - `:explicit` + - `read_only: bool` - - `class BetaResponseInputImage` + Indicates whether or not a tool modifies data or is read-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 image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `tool_names: Array[String]` - - `detail: :low | :high | :auto | :original` + List of allowed tool names. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `never: Never{ read_only, tool_names}` - - `:low` + A filter object to specify which tools are allowed. - - `:high` + - `read_only: bool` - - `:auto` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:original` + - `tool_names: Array[String]` - - `type: :input_image` + List of allowed tool names. - The type of the input item. Always `input_image`. + - `McpToolApprovalSetting = :always | :never` - - `:input_image` + 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. - - `file_id: String` + - `:always` - The ID of the file to be sent to the model. + - `:never` - - `image_url: String` + - `server_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. + Optional description of the MCP server, used to provide more context. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `server_url: String` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `mode: :explicit` + - `tunnel_id: String` - The breakpoint mode. Always `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. - - `:explicit` + - `class CodeInterpreter` - - `class BetaResponseInputFile` + A tool that runs Python code to help generate a response to a prompt. - A file input to the model. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `type: :input_file` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the input item. Always `input_file`. + - `String = String` - - `:input_file` + The container ID. - - `detail: :auto | :low | :high` + - `class CodeInterpreterToolAuto` - 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`. + 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: Array[String]` - - `:high` + An optional list of uploaded files to make available to your code. - - `file_data: String` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The content of the file to be sent to the model. + The memory limit for the code interpreter container. - - `file_id: String` + - `:"1g"` - The ID of the file to be sent to the model. + - `:"4g"` - - `file_url: String` + - `:"16g"` - The URL of the file to be sent to the model. + - `:"64g"` - - `filename: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The name of the file to be sent to the model. + Network access policy for the container. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class BetaContainerNetworkPolicyDisabled` - Marks the exact end of a reusable 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: :disabled` - - `mode: :explicit` + Disable outbound network access. Always `disabled`. - The breakpoint mode. Always `explicit`. + - `:disabled` - - `:explicit` + - `class BetaContainerNetworkPolicyAllowlist` - - `role: :user | :assistant | :system | :developer` + - `allowed_domains: Array[String]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + A list of allowed domains when type is `allowlist`. - - `:user` + - `type: :allowlist` - - `:assistant` + Allow outbound network access only to specified domains. Always `allowlist`. - - `:system` + - `:allowlist` - - `:developer` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `phase: :commentary` + Optional domain-scoped secrets for allowlisted domains. - 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. + - `domain: String` - - `:commentary` + The domain associated with the secret. - - `type: :message` + - `name: String` - The type of the message input. Always `message`. + The name of the secret to inject for the domain. - - `:message` + - `value: String` - - `class Message` + The secret value to inject for the domain. - 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: :code_interpreter` - - `content: BetaResponseInputMessageContentList` + The type of the code interpreter tool. Always `code_interpreter`. - A list of one or many input items to the model, containing different content - types. + - `:code_interpreter` - - `role: :user | :system | :developer` + - `allowed_callers: Array[:direct | :programmatic]` - The role of the message input. One of `user`, `system`, or `developer`. + The tool invocation context(s). - - `:user` + - `:direct` - - `:system` + - `:programmatic` - - `:developer` + - `class ProgrammaticToolCalling` - - `agent: Agent{ agent_name}` + - `type: :programmatic_tool_calling` - The agent that produced this item. + The type of the tool. Always `programmatic_tool_calling`. - - `agent_name: String` + - `:programmatic_tool_calling` - The canonical name of the agent that produced this item. + - `class ImageGeneration` - - `status: :in_progress | :completed | :incomplete` + A tool that generates images using the GPT image models. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: :image_generation` - - `:in_progress` + The type of the image generation tool. Always `image_generation`. - - `:completed` + - `:image_generation` - - `:incomplete` + - `action: :generate | :edit | :auto` - - `type: :message` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the message input. Always set to `message`. + - `:generate` - - `:message` + - `:edit` - - `class BetaResponseOutputMessage` + - `:auto` - An output message from the model. + - `background: :transparent | :opaque | :auto` - - `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 ID 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. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The content of the output message. + - `:transparent` - - `class BetaResponseOutputText` + - `:opaque` - A text output from the model. + - `:auto` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `input_fidelity: :high | :low` - The annotations of the text 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`. - - `class FileCitation` + - `:high` - A citation to a file. + - `:low` + + - `input_image_mask: InputImageMask{ file_id, image_url}` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - `file_id: String` - The ID of the file. + File ID for the mask image. - - `filename: String` + - `image_url: String` - The filename of the file cited. + Base64-encoded mask image. - - `index: Integer` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - The index of the file in the list of files. + The image generation model to use. Default: `gpt-image-1`. - - `type: :file_citation` + - `String = String` - The type of the file citation. Always `file_citation`. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:file_citation` + The image generation model to use. Default: `gpt-image-1`. - - `class URLCitation` + - `:"gpt-image-1"` - A citation for a web resource used to generate a model response. + - `:"gpt-image-1-mini"` - - `end_index: Integer` + - `:"gpt-image-2"` - The index of the last character of the URL citation in the message. + - `:"gpt-image-2-2026-04-21"` - - `start_index: Integer` + - `:"gpt-image-1.5"` - The index of the first character of the URL citation in the message. + - `:"chatgpt-image-latest"` - - `title: String` + - `moderation: :auto | :low` - The title of the web resource. + Moderation level for the generated image. Default: `auto`. - - `type: :url_citation` + - `:auto` - The type of the URL citation. Always `url_citation`. + - `:low` - - `:url_citation` + - `output_compression: Integer` - - `url: String` + Compression level for the output image. Default: 100. - The URL of the web resource. + - `output_format: :png | :webp | :jpeg` - - `class ContainerFileCitation` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - A citation for a container file used to generate a model response. + - `:png` - - `container_id: String` + - `:webp` - The ID of the container file. + - `:jpeg` - - `end_index: Integer` + - `partial_images: Integer` - The index of the last character of the container file citation in the message. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `file_id: String` + - `quality: :low | :medium | :high | :auto` - The ID of the file. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `filename: String` + - `:low` - The filename of the container file cited. + - `:medium` + + - `:high` + + - `:auto` + + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `start_index: Integer` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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 first character of the container file citation in the message. + - `String = String` - - `type: :container_file_citation` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - The type of the container file citation. Always `container_file_citation`. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `:container_file_citation` + - `:"1024x1024"` - - `class FilePath` + - `:"1024x1536"` - A path to a file. + - `:"1536x1024"` - - `file_id: String` + - `:auto` - The ID of the file. + - `class LocalShell` - - `index: Integer` + A tool that allows the model to execute shell commands in a local environment. - The index of the file in the list of files. + - `type: :local_shell` - - `type: :file_path` + The type of the local shell tool. Always `local_shell`. - The type of the file path. Always `file_path`. + - `:local_shell` - - `:file_path` + - `class BetaFunctionShellTool` - - `text: String` + A tool that allows the model to execute shell commands. - The text output from the model. + - `type: :shell` - - `type: :output_text` + The type of the shell tool. Always `shell`. - The type of the output text. Always `output_text`. + - `:shell` - - `:output_text` + - `allowed_callers: Array[:direct | :programmatic]` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The tool invocation context(s). - - `token: String` + - `:direct` - - `bytes: Array[Integer]` + - `:programmatic` - - `logprob: Float` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `class BetaContainerAuto` - - `token: String` + - `type: :container_auto` - - `bytes: Array[Integer]` + Automatically creates a container for this request - - `logprob: Float` + - `:container_auto` - - `class BetaResponseOutputRefusal` + - `file_ids: Array[String]` - A refusal from the model. + An optional list of uploaded files to make available to your code. - - `refusal: String` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The refusal explanation from the model. + The memory limit for the container. - - `type: :refusal` + - `:"1g"` - The type of the refusal. Always `refusal`. + - `:"4g"` - - `:refusal` + - `:"16g"` - - `role: :assistant` + - `:"64g"` - The role of the output message. Always `assistant`. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:assistant` + Network access policy for the container. - - `status: :in_progress | :completed | :incomplete` + - `class BetaContainerNetworkPolicyDisabled` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaContainerNetworkPolicyAllowlist` - - `:in_progress` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `:completed` + An optional list of skills referenced by id or inline data. - - `:incomplete` + - `class BetaSkillReference` - - `type: :message` + - `skill_id: String` - The type of the output message. Always `message`. + The ID of the referenced skill. - - `:message` + - `type: :skill_reference` - - `agent: Agent{ agent_name}` + References a skill created with the /v1/skills endpoint. - The agent that produced this item. + - `:skill_reference` - - `agent_name: String` + - `version: String` - The canonical name of the agent that produced this item. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `phase: :commentary` + - `class BetaInlineSkill` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `description: String` - - `:commentary` + The description of the skill. - - `class BetaResponseFileSearchToolCall` + - `name: String` - 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 name of the skill. - - `id: String` + - `source: BetaInlineSkillSource` - The unique ID of the file search tool call. + Inline skill payload - - `queries: Array[String]` + - `data: String` - The queries used to search for files. + Base64-encoded skill zip bundle. - - `status: :in_progress | :searching | :completed | 2 more` + - `media_type: :"application/zip"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The media type of the inline skill payload. Must be `application/zip`. - - `:in_progress` + - `:"application/zip"` - - `:searching` + - `type: :base64` - - `:completed` + The type of the inline skill source. Must be `base64`. - - `:incomplete` + - `:base64` - - `:failed` + - `type: :inline` - - `type: :file_search_call` + Defines an inline skill for this request. - The type of the file search tool call. Always `file_search_call`. + - `:inline` - - `:file_search_call` + - `class BetaLocalEnvironment` - - `agent: Agent{ agent_name}` + - `type: :local` - The agent that produced this item. + Use a local computer environment. - - `agent_name: String` + - `:local` - The canonical name of the agent that produced this item. + - `skills: Array[BetaLocalSkill]` - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + An optional list of skills. - The results of the file search tool call. + - `description: String` - - `attributes: Hash[Symbol, String | Float | bool]` + The description of the skill. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `name: String` - - `String = String` + The name of the skill. - - `Float = Float` + - `path: String` - - `UnionMember2 = bool` + The path to the directory containing the skill. - - `file_id: String` + - `class BetaContainerReference` - The unique ID of the file. + - `container_id: String` - - `filename: String` + The ID of the referenced container. - The name of the file. + - `type: :container_reference` - - `score: Float` + References a container created with the /v1/containers endpoint - The relevance score of the file - a value between 0 and 1. + - `:container_reference` - - `text: String` + - `class BetaCustomTool` - The text that was retrieved from the file. + 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) - - `class BetaResponseComputerToolCall` + - `name: 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. + The name of the custom tool, used to identify it in tool calls. - - `id: String` + - `type: :custom` - The unique ID of the computer call. + The type of the custom tool. Always `custom`. - - `call_id: String` + - `:custom` - An identifier used when responding to the tool call with output. + - `allowed_callers: Array[:direct | :programmatic]` - - `pending_safety_checks: Array[PendingSafetyCheck{ 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: bool` - - `code: String` + Whether this tool should be deferred and discovered via tool search. - The type of the pending safety check. + - `description: String` - - `message: String` + Optional description of the custom tool, used to provide more context. - Details about the pending safety check. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `status: :in_progress | :completed | :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. + - `class Text` - - `:in_progress` + Unconstrained free-form text. - - `:completed` + - `type: :text` - - `:incomplete` + Unconstrained text format. Always `text`. - - `type: :computer_call` + - `:text` - The type of the computer call. Always `computer_call`. + - `class Grammar` - - `:computer_call` + A grammar defined by the user. - - `action: BetaComputerAction` + - `definition: String` - A click action. + The grammar definition. - - `class Click` + - `syntax: :lark | :regex` - A click action. + The syntax of the grammar definition. One of `lark` or `regex`. - - `button: :left | :right | :wheel | 2 more` + - `:lark` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `:regex` - - `:left` + - `type: :grammar` - - `:right` + Grammar format. Always `grammar`. - - `:wheel` + - `:grammar` - - `:back` + - `class BetaNamespaceTool` - - `:forward` + Groups function/custom tools under a shared namespace. - - `type: :click` + - `description: String` - Specifies the event type. For a click action, this property is always `click`. + A description of the namespace shown to the model. - - `:click` + - `name: String` - - `x: Integer` + The namespace name used in tool calls (for example, `crm`). - The x-coordinate where the click occurred. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `y_: Integer` + The function/custom tools available inside this namespace. - The y-coordinate where the click occurred. + - `class Function` - - `keys: Array[String]` + - `name: String` - The keys being held while clicking. + - `type: :function` - - `class DoubleClick` + - `:function` - A double click action. + - `allowed_callers: Array[:direct | :programmatic]` - - `keys: Array[String]` + The tool invocation context(s). - The keys being held while double-clicking. + - `:direct` - - `type: :double_click` + - `:programmatic` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `defer_loading: bool` - - `:double_click` + Whether this function should be deferred and discovered via tool search. - - `x: Integer` + - `description: String` - The x-coordinate where the double click occurred. + - `output_schema: Hash[Symbol, untyped]` - - `y_: Integer` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The y-coordinate where the double click occurred. + - `parameters: untyped` - - `class Drag` + - `strict: bool` - A drag action. + 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. - - `path: Array[Path{ x, y_}]` + - `class BetaCustomTool` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + 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) - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `type: :namespace` - - `x: Integer` + The type of the tool. Always `namespace`. - The x-coordinate. + - `:namespace` - - `y_: Integer` + - `class BetaToolSearchTool` - The y-coordinate. + Hosted or BYOT tool search configuration for deferred tools. - - `type: :drag` + - `type: :tool_search` - Specifies the event type. For a drag action, this property is always set to `drag`. + The type of the tool. Always `tool_search`. - - `:drag` + - `:tool_search` - - `keys: Array[String]` + - `description: String` - The keys being held while dragging the mouse. + Description shown to the model for a client-executed tool search tool. - - `class Keypress` + - `execution: :server | :client` - A collection of keypresses the model would like to perform. + Whether tool search is executed by the server or by the client. - - `keys: Array[String]` + - `:server` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `:client` - - `type: :keypress` + - `parameters: untyped` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Parameter schema for a client-executed tool search tool. - - `:keypress` + - `class BetaWebSearchPreviewTool` - - `class Move` + 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 mouse move action. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `type: :move` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Specifies the event type. For a move action, this property is always set to `move`. + - `:web_search_preview` - - `:move` + - `:web_search_preview_2025_03_11` - - `x: Integer` + - `search_content_types: Array[:text | :image]` - The x-coordinate to move to. + - `:text` - - `y_: Integer` + - `:image` - The y-coordinate to move to. + - `search_context_size: :low | :medium | :high` - - `keys: Array[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 moving the mouse. + - `:low` - - `class Screenshot` + - `:medium` - A screenshot action. + - `:high` - - `type: :screenshot` + - `user_location: UserLocation{ type, city, country, 2 more}` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The user's location. - - `:screenshot` + - `type: :approximate` - - `class Scroll` + The type of location approximation. Always `approximate`. - A scroll action. + - `:approximate` - - `scroll_x: Integer` + - `city: String` - The horizontal scroll distance. + Free text input for the city of the user, e.g. `San Francisco`. - - `scroll_y: Integer` + - `country: String` - The vertical scroll distance. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: :scroll` + - `region: String` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Free text input for the region of the user, e.g. `California`. - - `:scroll` + - `timezone: String` - - `x: Integer` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The x-coordinate where the scroll occurred. + - `class BetaApplyPatchTool` - - `y_: Integer` + Allows the assistant to create, delete, or update files using unified diffs. - The y-coordinate where the scroll occurred. + - `type: :apply_patch` - - `keys: Array[String]` + The type of the tool. Always `apply_patch`. - The keys being held while scrolling. + - `:apply_patch` - - `class Type` + - `allowed_callers: Array[:direct | :programmatic]` - An action to type in text. + The tool invocation context(s). - - `text: String` + - `:direct` - The text to type. + - `:programmatic` - - `type: :type` + - `type: :tool_search_output` - Specifies the event type. For a type action, this property is always set to `type`. + The type of the item. Always `tool_search_output`. - - `:type` + - `:tool_search_output` - - `class Wait` + - `agent: Agent{ 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` + - `created_by: String` - - `actions: BetaComputerActionList` + The identifier of the actor that created the item. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `class AdditionalTools` - - `class Click` + - `id: String` - A click action. + The unique ID of the additional tools item. - - `class DoubleClick` + - `role: :unknown | :user | :assistant | 5 more` - A double click action. + The role that provided the additional tools. - - `class Drag` + - `:unknown` - A drag action. + - `:user` - - `class Keypress` + - `:assistant` - A collection of keypresses the model would like to perform. + - `:system` - - `class Move` + - `:critic` - A mouse move action. + - `:discriminator` - - `class Screenshot` + - `:developer` - A screenshot action. + - `:tool` - - `class Scroll` + - `tools: Array[BetaTool]` - A scroll action. + The additional tool definitions made available at this item. - - `class Type` + - `class BetaFunctionTool` - An action to type in text. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class Wait` + - `class BetaFileSearchTool` - A wait action. + 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: Agent{ agent_name}` + - `class BetaComputerTool` - 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` + - `class BetaComputerUsePreviewTool` - 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). - - `class ComputerCallOutput` + - `class BetaWebSearchTool` - 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` + - `class Mcp` - The ID of the computer tool call that produced the output. + 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: BetaResponseComputerToolCallOutputScreenshot` + - `class CodeInterpreter` - A computer screenshot image used with the computer use tool. + A tool that runs Python code to help generate a response to a prompt. - - `type: :computer_screenshot` + - `class ProgrammaticToolCalling` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `class ImageGeneration` - - `:computer_screenshot` + A tool that generates images using the GPT image models. - - `file_id: String` + - `class LocalShell` - The identifier of an uploaded file that contains the screenshot. + A tool that allows the model to execute shell commands in a local environment. - - `image_url: String` + - `class BetaFunctionShellTool` - The URL of the screenshot image. + A tool that allows the model to execute shell commands. - - `type: :computer_call_output` + - `class BetaCustomTool` - The type of the computer tool call output. Always `computer_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) - - `:computer_call_output` + - `class BetaNamespaceTool` - - `id: String` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call output. + - `class BetaToolSearchTool` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + Hosted or BYOT tool search configuration for deferred tools. - The safety checks reported by the API that have been acknowledged by the developer. + - `class BetaWebSearchPreviewTool` - - `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 pending safety check. + - `class BetaApplyPatchTool` - - `code: String` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the pending safety check. + - `type: :additional_tools` - - `message: String` + The type of the item. Always `additional_tools`. - Details about the pending safety check. + - `:additional_tools` - `agent: Agent{ agent_name}` @@ -94602,146 +106073,142 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `class BetaResponseCompactionItem` - - `:in_progress` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:completed` + - `id: String` - - `:incomplete` + The unique ID of the compaction item. - - `class BetaResponseFunctionWebSearch` + - `encrypted_content: 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 encrypted content that was produced by compaction. - - `id: String` + - `type: :compaction` - The unique ID of the web search tool call. + The type of the item. Always `compaction`. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `:compaction` - 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). + - `agent: Agent{ agent_name}` - - `class Search` + The agent that produced this item. - Action type "search" - Performs a web search query. + - `agent_name: String` - - `type: :search` + The canonical name of the agent that produced this item. - The action type. + - `created_by: String` - - `:search` + The identifier of the actor that created the item. - - `queries: Array[String]` + - `class ImageGenerationCall` - The search queries. + An image generation request made by the model. - - `query: String` + - `id: String` - The search query. + The unique ID of the image generation call. - - `sources: Array[Source{ type, url}]` + - `result: String` - The sources used in the search. + The generated image encoded in base64. - - `type: :url` + - `status: :in_progress | :completed | :generating | :failed` - The type of source. Always `url`. + The status of the image generation call. - - `:url` + - `:in_progress` - - `url: String` + - `:completed` - The URL of the source. + - `:generating` - - `class OpenPage` + - `:failed` - Action type "open_page" - Opens a specific URL from search results. + - `type: :image_generation_call` - - `type: :open_page` + The type of the image generation call. Always `image_generation_call`. - The action type. + - `:image_generation_call` - - `:open_page` + - `agent: Agent{ agent_name}` - - `url: String` + The agent that produced this item. - The URL opened by the model. + - `agent_name: String` - - `class FindInPage` + The canonical name of the agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `class BetaResponseCodeInterpreterToolCall` - - `pattern: String` + A tool call to run code. - The pattern or text to search for within the page. + - `id: String` - - `type: :find_in_page` + The unique ID of the code interpreter tool call. - The action type. + - `code: String` - - `:find_in_page` + The code to run, or null if not available. - - `url: String` + - `container_id: String` - The URL of the page searched for the pattern. + The ID of the container used to run the code. - - `status: :in_progress | :searching | :completed | :failed` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - The status of the web search tool call. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `:in_progress` + - `class Logs` - - `:searching` + The logs output from the code interpreter. - - `:completed` + - `logs: String` - - `:failed` + The logs output from the code interpreter. - - `type: :web_search_call` + - `type: :logs` - The type of the web search tool call. Always `web_search_call`. + The type of the output. Always `logs`. - - `:web_search_call` + - `:logs` - - `agent: Agent{ agent_name}` + - `class Image` - The agent that produced this item. + The image output from the code interpreter. - - `agent_name: String` + - `type: :image` - The canonical name of the agent that produced this item. + The type of the output. Always `image`. - - `class BetaResponseFunctionToolCall` + - `:image` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `url: String` - - `arguments: String` + The URL of the image output from the code interpreter. - A JSON string of the arguments to pass to the function. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `call_id: String` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The unique ID of the function tool call generated by the model. + - `:in_progress` - - `name: String` + - `:completed` - The name of the function to run. + - `:incomplete` - - `type: :function_call` + - `:interpreting` - The type of the function tool call. Always `function_call`. + - `:failed` - - `:function_call` + - `type: :code_interpreter_call` - - `id: String` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The unique ID of the function tool call. + - `:code_interpreter_call` - `agent: Agent{ agent_name}` @@ -94751,180 +106218,175 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class LocalShellCall` - The execution context that produced this tool call. + A tool call to run a command on the local shell. - - `class Direct` + - `id: String` - - `type: :direct` + The unique ID of the local shell call. - - `:direct` + - `action: Action{ command, env, type, 3 more}` - - `class Program` + Execute a shell command on the server. - - `caller_id: String` + - `command: Array[String]` - The call ID of the program item that produced this tool call. + The command to run. - - `type: :program` + - `env: Hash[Symbol, String]` - - `:program` + Environment variables to set for the command. - - `namespace: String` + - `type: :exec` - The namespace of the function to run. + The type of the local shell action. Always `exec`. - - `status: :in_progress | :completed | :incomplete` + - `:exec` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `timeout_ms: Integer` - - `:in_progress` + Optional timeout in milliseconds for the command. - - `:completed` + - `user: String` - - `:incomplete` + Optional user to run the command as. - - `class FunctionCallOutput` + - `working_directory: String` - The output of a function tool call. + Optional working directory to run the command in. - `call_id: String` - The unique ID of the function tool call generated by the model. - - - `output: String | BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. + The unique ID of the local shell tool call generated by the model. - - `String = String` + - `status: :in_progress | :completed | :incomplete` - A JSON string of the output of the function tool call. + The status of the local shell call. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `:in_progress` - An array of content outputs (text, image, file) for the function tool call. + - `:completed` - - `class BetaResponseInputTextContent` + - `:incomplete` - A text input to the model. + - `type: :local_shell_call` - - `text: String` + The type of the local shell call. Always `local_shell_call`. - The text input to the model. + - `:local_shell_call` - - `type: :input_text` + - `agent: Agent{ 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: PromptCacheBreakpoint{ 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. + - `class LocalShellCallOutput` - - `mode: :explicit` + The output of a local shell tool call. - The breakpoint mode. Always `explicit`. + - `id: String` - - `:explicit` + The unique ID of the local shell tool call generated by the model. - - `class BetaResponseInputImageContent` + - `output: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A JSON string of the output of the local shell tool call. - - `type: :input_image` + - `type: :local_shell_call_output` - The type of the input item. Always `input_image`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `:input_image` + - `:local_shell_call_output` - - `detail: :low | :high | :auto | :original` + - `agent: Agent{ agent_name}` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `:low` + - `agent_name: String` - - `:high` + The canonical name of the agent that produced this item. - - `:auto` + - `status: :in_progress | :completed | :incomplete` - - `:original` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `file_id: String` + - `:in_progress` - The ID of the file to be sent to the model. + - `:completed` - - `image_url: String` + - `:incomplete` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class BetaResponseFunctionShellToolCall` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A tool call that executes one or more shell commands in a managed environment. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `id: String` - - `mode: :explicit` + The unique ID of the shell tool call. Populated when this item is returned via API. - The breakpoint mode. Always `explicit`. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:explicit` + The shell commands and limits that describe how to run the tool call. - - `class BetaResponseInputFileContent` + - `commands: Array[String]` - A file input to the model. + - `max_output_length: Integer` - - `type: :input_file` + Optional maximum number of characters to return from each command. - The type of the input item. Always `input_file`. + - `timeout_ms: Integer` - - `:input_file` + Optional timeout in milliseconds for the commands. - - `detail: :auto | :low | :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 shell tool call generated by the model. - - `:auto` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:low` + Represents the use of a local environment to perform shell actions. - - `:high` + - `class BetaResponseLocalEnvironment` - - `file_data: String` + Represents the use of a local environment to perform shell actions. - The base64-encoded data of the file to be sent to the model. + - `type: :local` - - `file_id: String` + The environment type. Always `local`. - The ID of the file to be sent to the model. + - `:local` - - `file_url: String` + - `class BetaResponseContainerReference` - The URL of the file to be sent to the model. + Represents a container created with /v1/containers. - - `filename: String` + - `container_id: String` - The name of the file to be sent to the model. + - `type: :container_reference` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The environment type. Always `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. + - `:container_reference` - - `mode: :explicit` + - `status: :in_progress | :completed | :incomplete` - The breakpoint mode. Always `explicit`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:explicit` + - `:in_progress` - - `type: :function_call_output` + - `:completed` - The type of the function tool call output. Always `function_call_output`. + - `:incomplete` - - `:function_call_output` + - `type: :shell_call` - - `id: String` + The type of the item. Always `shell_call`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `:shell_call` - `agent: Agent{ agent_name}` @@ -94942,8 +106404,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -94954,265 +106414,257 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` + - `created_by: String` - - `class AgentMessage` + The ID of the entity that created this tool call. - A message routed between agents. + - `class BetaResponseFunctionShellToolCallOutput` - - `author: String` + The output of a shell tool call that was emitted. - The sending agent identity. + - `id: String` - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + The unique ID of the shell call output. Populated when this item is returned via API. - Plaintext, image, or encrypted content sent between agents. + - `call_id: String` - - `class BetaResponseInputTextContent` + The unique ID of the shell tool call generated by the model. - A text input to the model. + - `max_output_length: Integer` - - `class BetaResponseInputImageContent` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `class EncryptedContent` + An array of shell call output contents - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `encrypted_content: String` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Opaque encrypted content. + - `class Timeout` - - `type: :encrypted_content` + Indicates that the shell call exceeded its configured time limit. - The type of the input item. Always `encrypted_content`. + - `type: :timeout` - - `:encrypted_content` + The outcome type. Always `timeout`. - - `recipient: String` + - `:timeout` - The destination agent identity. + - `class Exit` - - `type: :agent_message` + Indicates that the shell commands finished and returned an exit code. - The item type. Always `agent_message`. + - `exit_code: Integer` - - `:agent_message` + Exit code from the shell process. - - `id: String` + - `type: :exit` - The unique ID of this agent message item. + The outcome type. Always `exit`. - - `agent: Agent{ agent_name}` + - `:exit` - The agent that produced this item. + - `stderr: String` - - `agent_name: String` + The standard error output that was captured. - The canonical name of the agent that produced this item. + - `stdout: String` - - `class MultiAgentCall` + The standard output that was captured. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `created_by: String` - The multi-agent action that was executed. + The identifier of the actor that created the item. - - `:spawn_agent` + - `status: :in_progress | :completed | :incomplete` - - `:interrupt_agent` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `:list_agents` + - `:in_progress` - - `:send_message` + - `:completed` - - `:followup_task` + - `:incomplete` - - `:wait_agent` + - `type: :shell_call_output` - - `arguments: String` + The type of the shell call output. Always `shell_call_output`. - The action arguments as a JSON string. + - `:shell_call_output` - - `call_id: String` + - `agent: Agent{ agent_name}` - The unique ID linking this call to its output. + The agent that produced this item. - - `type: :multi_agent_call` + - `agent_name: String` - The item type. Always `multi_agent_call`. + The canonical name of the agent that produced this item. - - `:multi_agent_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of this multi-agent call. + - `class Direct` - - `agent: Agent{ agent_name}` + - `type: :direct` - The agent that produced this item. + - `:direct` - - `agent_name: String` + - `class Program` - The canonical name of the agent that produced this item. + - `caller_id: String` - - `class MultiAgentCallOutput` + The call ID of the program item that produced this tool call. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :program` - The multi-agent action that produced this result. + - `:program` - - `:spawn_agent` + - `created_by: String` - - `:interrupt_agent` + The identifier of the actor that created the item. - - `:list_agents` + - `class BetaResponseApplyPatchToolCall` - - `:send_message` + A tool call that applies file diffs by creating, deleting, or updating files. - - `:followup_task` + - `id: String` - - `:wait_agent` + 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 multi-agent call. + The unique ID of the apply patch tool call generated by the model. - - `output: Array[Output{ text, type, annotations}]` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - Text output returned by the multi-agent action. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `text: String` + - `class CreateFile` - The text content. + Instruction describing how to create a file via the apply_patch tool. - - `type: :output_text` + - `diff: String` - The content type. Always `output_text`. + Diff to apply. - - `:output_text` + - `path: String` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + Path of the file to create. - Citations associated with the text content. + - `type: :create_file` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + Create a new file with the provided diff. - - `file_id: String` + - `:create_file` - The ID of the file. + - `class DeleteFile` - - `filename: String` + Instruction describing how to delete a file via the apply_patch tool. - The filename of the file cited. + - `path: String` - - `index: Integer` + Path of the file to delete. - The index of the file in the list of files. + - `type: :delete_file` - - `type: :file_citation` + Delete the specified file. - The citation type. Always `file_citation`. + - `:delete_file` - - `:file_citation` + - `class UpdateFile` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + Instruction describing how to update a file via the apply_patch tool. - - `end_index: Integer` + - `diff: String` - The index of the last character of the citation in the message. + Diff to apply. - - `start_index: Integer` + - `path: String` + + Path of the file to update. - The index of the first character of the citation in the message. + - `type: :update_file` - - `title: String` + Update an existing file with the provided diff. - The title of the cited resource. + - `:update_file` - - `type: :url_citation` + - `status: :in_progress | :completed` - The citation type. 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 cited resource. + - `type: :apply_patch_call` - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + The type of the item. Always `apply_patch_call`. - - `container_id: String` + - `:apply_patch_call` - The ID of the container. + - `agent: Agent{ agent_name}` - - `end_index: Integer` + The agent that produced this item. - The index of the last character of the citation in the message. + - `agent_name: String` - - `file_id: String` + The canonical name of the agent that produced this item. - The ID of the container file. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `filename: String` + The execution context that produced this tool call. - The filename of the container file cited. + - `class Direct` - - `start_index: Integer` + - `type: :direct` - The index of the first character of the citation in the message. + - `:direct` - - `type: :container_file_citation` + - `class Program` - The citation type. Always `container_file_citation`. + - `caller_id: String` - - `:container_file_citation` + The call ID of the program item that produced this tool call. - - `type: :multi_agent_call_output` + - `type: :program` - The item type. Always `multi_agent_call_output`. + - `:program` - - `:multi_agent_call_output` + - `created_by: String` - - `id: String` + The ID of the entity that created this tool call. - The unique ID of this multi-agent call output. + - `class BetaResponseApplyPatchToolCallOutput` - - `agent: Agent{ agent_name}` + The output emitted by an apply patch tool call. - The agent that produced this item. + - `id: String` - - `agent_name: String` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The canonical name of the agent that produced this item. + - `call_id: String` - - `class ToolSearchCall` + The unique ID of the apply patch tool call generated by the model. - - `arguments: untyped` + - `status: :completed | :failed` - The arguments supplied to the tool search call. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: :tool_search_call` + - `:completed` - The item type. Always `tool_search_call`. + - `:failed` - - `:tool_search_call` + - `type: :apply_patch_call_output` - - `id: String` + The type of the item. Always `apply_patch_call_output`. - The unique ID of this tool search call. + - `:apply_patch_call_output` - `agent: Agent{ agent_name}` @@ -95222,1129 +106674,1092 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The unique ID of the tool search call generated by the model. + The execution context that produced this tool call. - - `execution: :server | :client` + - `class Direct` - Whether tool search was executed by the server or by the client. + - `type: :direct` - - `:server` + - `:direct` - - `:client` + - `class Program` - - `status: :in_progress | :completed | :incomplete` + - `caller_id: String` - The status of the tool search call. + The call ID of the program item that produced this tool call. - - `:in_progress` + - `type: :program` - - `:completed` + - `:program` - - `:incomplete` + - `created_by: String` - - `class BetaResponseToolSearchOutputItemParam` + The ID of the entity that created this tool call output. - - `tools: Array[BetaTool]` + - `output: String` - The loaded tool definitions returned by the tool search output. + Optional textual output returned by the apply patch tool. - - `class BetaFunctionTool` + - `class McpCall` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + An invocation of a tool on an MCP server. - - `name: String` + - `id: String` - The name of the function to call. + The unique ID of the tool call. - - `parameters: Hash[Symbol, untyped]` + - `arguments: String` - A JSON schema object describing the parameters of the function. + A JSON string of the arguments passed to the tool. - - `strict: bool` + - `name: String` - Whether strict parameter validation is enforced for this function tool. + The name of the tool that was run. - - `type: :function` + - `server_label: String` - The type of the function tool. Always `function`. + The label of the MCP server running the tool. - - `:function` + - `type: :mcp_call` - - `allowed_callers: Array[:direct | :programmatic]` + The type of the item. Always `mcp_call`. - The tool invocation context(s). + - `:mcp_call` - - `:direct` + - `agent: Agent{ agent_name}` - - `:programmatic` + The agent that produced this item. - - `defer_loading: bool` + - `agent_name: String` - Whether this function is deferred and loaded via tool search. + The canonical name of the agent that produced this item. - - `description: String` + - `approval_request_id: String` - A description of the function. Used by the model to determine whether or not to call the 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. - - `output_schema: Hash[Symbol, untyped]` + - `error: String` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The error from the tool call, if any. - - `class BetaFileSearchTool` + - `output: 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 output from the tool call. - - `type: :file_search` + - `status: :in_progress | :completed | :incomplete | 2 more` - The type of the file search tool. Always `file_search`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `:file_search` + - `:in_progress` - - `vector_store_ids: Array[String]` + - `:completed` - The IDs of the vector stores to search. + - `:incomplete` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `:calling` - A filter to apply. + - `:failed` - - `class ComparisonFilter` + - `class McpListTools` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A list of tools available on an MCP server. - - `key: String` + - `id: String` - The key to compare against the value. + The unique ID of the list. - - `type: :eq | :ne | :gt | 5 more` + - `server_label: String` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The label of the MCP server. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `:eq` + The tools available on the server. - - `:ne` + - `input_schema: untyped` - - `:gt` + The JSON schema describing the tool's input. - - `:gte` + - `name: String` - - `:lt` + The name of the tool. - - `:lte` + - `annotations: untyped` - - `:in` + Additional annotations about the tool. - - `:nin` + - `description: String` - - `value: String | Float | bool | Array[untyped]` + The description of the tool. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: :mcp_list_tools` - - `String = String` + The type of the item. Always `mcp_list_tools`. - - `Float = Float` + - `:mcp_list_tools` - - `UnionMember2 = bool` + - `agent: Agent{ agent_name}` - - `UnionMember3 = Array[untyped]` + The agent that produced this item. - - `class CompoundFilter` + - `agent_name: String` - Combine multiple filters using `and` or `or`. + The canonical name of the agent that produced this item. - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + - `error: String` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Error message if the server could not list tools. - - `class ComparisonFilter` + - `class McpApprovalRequest` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A request for human approval of a tool invocation. - - `key: String` + - `id: String` - The key to compare against the value. + The unique ID of the approval request. - - `type: :eq | :ne | :gt | 5 more` + - `arguments: String` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A JSON string of arguments for the 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 + - `name: String` - - `:eq` + The name of the tool to run. - - `:ne` + - `server_label: String` - - `:gt` + The label of the MCP server making the request. - - `:gte` + - `type: :mcp_approval_request` - - `:lt` + The type of the item. Always `mcp_approval_request`. - - `:lte` + - `:mcp_approval_request` - - `:in` + - `agent: Agent{ agent_name}` - - `:nin` + The agent that produced this item. - - `value: String | Float | bool | Array[untyped]` + - `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 = String` + - `class McpApprovalResponse` - - `Float = Float` + A response to an MCP approval request. - - `UnionMember2 = bool` + - `id: String` - - `UnionMember3 = Array[untyped]` + The unique ID of the approval response - - `UnionMember1 = untyped` + - `approval_request_id: String` - - `type: :and | :or` + The ID of the approval request being answered. - Type of operation: `and` or `or`. + - `approve: bool` - - `:and` + Whether the request was approved. - - `:or` + - `type: :mcp_approval_response` - - `max_num_results: Integer` + The type of the item. Always `mcp_approval_response`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `:mcp_approval_response` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `agent: Agent{ agent_name}` - Ranking options for search. + The agent that produced this item. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `agent_name: String` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The canonical name of the agent that produced this item. - - `embedding_weight: Float` + - `reason: String` - The weight of the embedding in the reciprocal ranking fusion. + Optional reason for the decision. - - `text_weight: Float` + - `class BetaResponseCustomToolCall` - The weight of the text in the reciprocal ranking fusion. + A call to a custom tool created by the model. - - `ranker: :auto | :"default-2024-11-15"` + - `call_id: String` - The ranker to use for the file search. + An identifier used to map this custom tool call to a tool call output. - - `:auto` + - `input: String` - - `:"default-2024-11-15"` + The input for the custom tool call generated by the model. - - `score_threshold: Float` + - `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 custom tool being called. - - `class BetaComputerTool` + - `type: :custom_tool_call` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the custom tool call. Always `custom_tool_call`. - - `type: :computer` + - `:custom_tool_call` - The type of the computer tool. Always `computer`. + - `id: String` - - `:computer` + The unique ID of the custom tool call in the OpenAI platform. - - `class BetaComputerUsePreviewTool` + - `agent: Agent{ agent_name}` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `display_height: Integer` + - `agent_name: String` - The height of the computer display. + The canonical name of the agent that produced this item. - - `display_width: Integer` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The width of the computer display. + The execution context that produced this tool call. - - `environment: :windows | :mac | :linux | 2 more` + - `class Direct` - The type of computer environment to control. + - `type: :direct` - - `:windows` + - `:direct` - - `:mac` + - `class Program` - - `:linux` + - `caller_id: String` - - `:ubuntu` + The call ID of the program item that produced this tool call. - - `:browser` + - `type: :program` - - `type: :computer_use_preview` + - `:program` - The type of the computer use tool. Always `computer_use_preview`. + - `namespace: String` - - `:computer_use_preview` + The namespace of the custom tool being called. - - `class BetaWebSearchTool` + - `class BetaResponseCustomToolCallOutputItem` - 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 output of a custom tool call from your code, being sent back to the model. - - `type: :web_search | :web_search_2025_08_26` + - `id: String` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The unique ID of the custom tool call output item. - - `:web_search` + - `status: :in_progress | :completed | :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: Filters{ allowed_domains}` + - `:in_progress` - Filters for the search. + - `:completed` - - `allowed_domains: Array[String]` + - `:incomplete` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `created_by: String` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The identifier of the actor that created the item. - - `search_context_size: :low | :medium | :high` + - `output_index: Integer` - High 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 output item that was added. - - `:low` + - `sequence_number: Integer` - - `:medium` + The sequence number of this event. - - `:high` + - `type: :"response.output_item.added"` - - `user_location: UserLocation{ city, country, region, 2 more}` + The type of the event. Always `response.output_item.added`. - The approximate location of the user. + - `:"response.output_item.added"` - - `city: String` + - `agent: Agent{ agent_name}` - Free text input for the city of the user, e.g. `San Francisco`. + The agent that owns this multi-agent streaming event. - - `country: 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: String` +### Beta Response Output Item Done Event - Free text input for the region of the user, e.g. `California`. +- `class BetaResponseOutputItemDoneEvent` - - `timezone: String` + Emitted when an output item is marked done. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `item: BetaResponseOutputItem` - - `type: :approximate` + The output item that was marked done. - The type of location approximation. Always `approximate`. + - `class BetaResponseOutputMessage` - - `:approximate` + An output message from the model. - - `class Mcp` + - `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 output message. - - `server_label: String` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - A label for this MCP server, used to identify it in tool calls. + The content of the output message. - - `type: :mcp` + - `class BetaResponseOutputText` - The type of the MCP tool. Always `mcp`. + A text output from the model. - - `:mcp` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `allowed_callers: Array[:direct | :programmatic]` + The annotations of the text output. - The tool invocation context(s). + - `class FileCitation` - - `:direct` + A citation to a file. - - `:programmatic` + - `file_id: String` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + The ID of the file. - List of allowed tool names or a filter object. + - `filename: String` - - `McpAllowedTools = Array[String]` + The filename of the file cited. - A string array of allowed tool names + - `index: Integer` - - `class McpToolFilter` + The index of the file in the list of files. - A filter object to specify which tools are allowed. + - `type: :file_citation` - - `read_only: bool` + The type of the file citation. Always `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. + - `:file_citation` - - `tool_names: Array[String]` + - `class URLCitation` - List of allowed tool names. + A citation for a web resource used to generate a model response. - - `authorization: String` + - `end_index: Integer` - 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 last character of the URL citation in the message. - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `start_index: Integer` - 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 first character of the URL citation in the message. - Currently supported `connector_id` values are: + - `title: 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 title of the web resource. - - `:connector_dropbox` + - `type: :url_citation` - - `:connector_gmail` + The type of the URL citation. Always `url_citation`. - - `:connector_googlecalendar` + - `:url_citation` - - `:connector_googledrive` + - `url: String` - - `:connector_microsoftteams` + The URL of the web resource. - - `:connector_outlookcalendar` + - `class ContainerFileCitation` - - `:connector_outlookemail` + A citation for a container file used to generate a model response. - - `:connector_sharepoint` + - `container_id: String` - - `defer_loading: bool` + The ID of the container file. - Whether this MCP tool is deferred and discovered via tool search. + - `end_index: Integer` - - `headers: Hash[Symbol, String]` + The index of the last character of the container file citation in the message. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `file_id: String` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + The ID of the file. - Specify which of the MCP server's tools require approval. + - `filename: String` - - `class McpToolApprovalFilter` + The filename of the container file cited. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `start_index: Integer` - - `always: Always{ read_only, tool_names}` + The index of the first character of the container file citation in the message. - A filter object to specify which tools are allowed. + - `type: :container_file_citation` - - `read_only: bool` + The type of the container file citation. Always `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. + - `:container_file_citation` - - `tool_names: Array[String]` + - `class FilePath` - List of allowed tool names. + A path to a file. - - `never: Never{ read_only, tool_names}` + - `file_id: String` - A filter object to specify which tools are allowed. + The ID of the file. - - `read_only: bool` + - `index: Integer` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The index of the file in the list of files. - - `tool_names: Array[String]` + - `type: :file_path` - List of allowed tool names. + The type of the file path. Always `file_path`. - - `McpToolApprovalSetting = :always | :never` + - `:file_path` - 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 output from the model. - - `:never` + - `type: :output_text` - - `server_description: String` + The type of the output text. Always `output_text`. - Optional description of the MCP server, used to provide more context. + - `:output_text` - - `server_url: String` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `token: String` - - `tunnel_id: String` + - `bytes: Array[Integer]` - 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. + - `logprob: Float` - - `class CodeInterpreter` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - A tool that runs Python code to help generate a response to a prompt. + - `token: String` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `bytes: Array[Integer]` - 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. + - `logprob: Float` - - `String = String` + - `class BetaResponseOutputRefusal` - The container ID. + A refusal from the model. - - `class CodeInterpreterToolAuto` + - `refusal: String` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The refusal explanation from the model. - - `type: :auto` + - `type: :refusal` - Always `auto`. + The type of the refusal. Always `refusal`. - - `:auto` + - `:refusal` - - `file_ids: Array[String]` + - `role: :assistant` - An optional list of uploaded files to make available to your code. + The role of the output message. Always `assistant`. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:assistant` - The memory limit for the code interpreter container. + - `status: :in_progress | :completed | :incomplete` - - `:"1g"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `:"4g"` + - `:in_progress` - - `:"16g"` + - `:completed` - - `:"64g"` + - `:incomplete` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :message` - Network access policy for the container. + The type of the output message. Always `message`. - - `class BetaContainerNetworkPolicyDisabled` + - `:message` - - `type: :disabled` + - `agent: Agent{ agent_name}` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `:disabled` + - `agent_name: String` - - `class BetaContainerNetworkPolicyAllowlist` + The canonical name of the agent that produced this item. - - `allowed_domains: Array[String]` + - `phase: :commentary | :final_answer` - A list of allowed domains when type is `allowlist`. + 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: :allowlist` + - `:commentary` - Allow outbound network access only to specified domains. Always `allowlist`. + - `:final_answer` - - `:allowlist` + - `class BetaResponseFileSearchToolCall` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + 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. - Optional domain-scoped secrets for allowlisted domains. + - `id: String` - - `domain: String` + The unique ID of the file search tool call. - The domain associated with the secret. + - `queries: Array[String]` - - `name: String` + The queries used to search for files. - The name of the secret to inject for the domain. + - `status: :in_progress | :searching | :completed | 2 more` - - `value: String` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The secret value to inject for the domain. + - `:in_progress` - - `type: :code_interpreter` + - `:searching` - The type of the code interpreter tool. Always `code_interpreter`. + - `:completed` - - `:code_interpreter` + - `:incomplete` - - `allowed_callers: Array[:direct | :programmatic]` + - `:failed` - The tool invocation context(s). + - `type: :file_search_call` - - `:direct` + The type of the file search tool call. Always `file_search_call`. - - `:programmatic` + - `:file_search_call` - - `class ProgrammaticToolCalling` + - `agent: Agent{ agent_name}` - - `type: :programmatic_tool_calling` + The agent that produced this item. - The type of the tool. Always `programmatic_tool_calling`. + - `agent_name: String` - - `:programmatic_tool_calling` + The canonical name of the agent that produced this item. - - `class ImageGeneration` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - A tool that generates images using the GPT image models. + The results of the file search tool call. - - `type: :image_generation` + - `attributes: Hash[Symbol, String | Float | bool]` - The type of the image generation tool. Always `image_generation`. + Set of 16 key-value pairs that can be attached to an object. 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. - - `:image_generation` + - `String = String` - - `action: :generate | :edit | :auto` + - `Float = Float` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `UnionMember2 = bool` - - `:generate` + - `file_id: String` - - `:edit` + The unique ID of the file. - - `:auto` + - `filename: String` - - `background: :transparent | :opaque | :auto` + The name of the file. - 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. + - `score: Float` - `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 relevance score of the file - a value between 0 and 1. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `text: String` - - `:transparent` + The text that was retrieved from the file. - - `:opaque` + - `class BetaResponseFunctionToolCall` - - `:auto` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `input_fidelity: :high | :low` + - `arguments: 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 JSON string of the arguments to pass to the function. - - `:high` + - `call_id: String` - - `:low` + The unique ID of the function tool call generated by the model. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `name: String` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The name of the function to run. - - `file_id: String` + - `type: :function_call` - File ID for the mask image. + The type of the function tool call. Always `function_call`. - - `image_url: String` + - `:function_call` - Base64-encoded mask image. + - `id: String` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The unique ID of the function tool call. - The image generation model to use. Default: `gpt-image-1`. + - `agent: Agent{ agent_name}` - - `String = String` + The agent that produced this item. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. - - `:"gpt-image-1"` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:"gpt-image-1-mini"` + The execution context that produced this tool call. - - `:"gpt-image-2"` + - `class Direct` - - `:"gpt-image-2-2026-04-21"` + - `type: :direct` - - `:"gpt-image-1.5"` + - `:direct` - - `:"chatgpt-image-latest"` + - `class Program` - - `moderation: :auto | :low` + - `caller_id: String` - Moderation level for the generated image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `:auto` + - `type: :program` - - `:low` + - `:program` - - `output_compression: Integer` + - `namespace: String` - Compression level for the output image. Default: 100. + The namespace of the function to run. - - `output_format: :png | :webp | :jpeg` + - `status: :in_progress | :completed | :incomplete` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:png` + - `:in_progress` - - `:webp` + - `:completed` - - `:jpeg` + - `:incomplete` - - `partial_images: Integer` + - `class BetaResponseFunctionToolCallOutputItem` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `id: String` - - `quality: :low | :medium | :high | :auto` + The unique ID of the function call tool output. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `call_id: String` - - `:low` + The unique ID of the function tool call generated by the model. - - `:medium` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:high` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:auto` + - `String = String` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + A string of the output of the function 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`. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `String = String` + Text, image, or file output of the function call. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `class BetaResponseInputText` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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"` + - `text: String` - - `:"1024x1536"` + The text input to the model. - - `:"1536x1024"` + - `type: :input_text` - - `:auto` + The type of the input item. Always `input_text`. - - `class LocalShell` + - `:input_text` - A tool that allows the model to execute shell commands in a local environment. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `type: :local_shell` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of the local shell tool. Always `local_shell`. + - `mode: :explicit` - - `:local_shell` + The breakpoint mode. Always `explicit`. - - `class BetaFunctionShellTool` + - `:explicit` - A tool that allows the model to execute shell commands. + - `class BetaResponseInputImage` - - `type: :shell` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of the shell tool. Always `shell`. + - `detail: :low | :high | :auto | :original` - - `:shell` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:low` - The tool invocation context(s). + - `:high` - - `:direct` + - `:auto` - - `:programmatic` + - `:original` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `type: :input_image` - - `class BetaContainerAuto` + The type of the input item. Always `input_image`. - - `type: :container_auto` + - `:input_image` - Automatically creates a container for this request + - `file_id: String` - - `:container_auto` + The ID of the file to be sent to the model. - - `file_ids: Array[String]` + - `image_url: String` - An optional list of uploaded files to make available to your code. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The memory limit 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. - - `:"1g"` + - `mode: :explicit` - - `:"4g"` + The breakpoint mode. Always `explicit`. - - `:"16g"` + - `:explicit` - - `:"64g"` + - `class BetaResponseInputFile` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + A file input to the model. - Network access policy for the container. + - `type: :input_file` - - `class BetaContainerNetworkPolicyDisabled` + The type of the input item. Always `input_file`. - - `class BetaContainerNetworkPolicyAllowlist` + - `:input_file` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `detail: :auto | :low | :high` - An optional list of skills referenced by id or inline data. + 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`. - - `class BetaSkillReference` + - `:auto` - - `skill_id: String` + - `:low` - The ID of the referenced skill. + - `:high` - - `type: :skill_reference` + - `file_data: String` - References a skill created with the /v1/skills endpoint. + The content of the file to be sent to the model. - - `:skill_reference` + - `file_id: String` - - `version: String` + The ID of the file to be sent to the model. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `file_url: String` - - `class BetaInlineSkill` + The URL of the file to be sent to the model. - - `description: String` + - `filename: String` - The description of the skill. + The name of the file to be sent to the model. - - `name: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The name of the skill. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `source: BetaInlineSkillSource` + - `mode: :explicit` - Inline skill payload + The breakpoint mode. Always `explicit`. - - `data: String` + - `:explicit` - Base64-encoded skill zip bundle. + - `status: :in_progress | :completed | :incomplete` - - `media_type: :"application/zip"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The media type of the inline skill payload. Must be `application/zip`. + - `:in_progress` - - `:"application/zip"` + - `:completed` - - `type: :base64` + - `:incomplete` - The type of the inline skill source. Must be `base64`. + - `type: :function_call_output` - - `:base64` + The type of the function tool call output. Always `function_call_output`. - - `type: :inline` + - `:function_call_output` - Defines an inline skill for this request. + - `agent: Agent{ agent_name}` - - `:inline` + The agent that produced this item. - - `class BetaLocalEnvironment` + - `agent_name: String` - - `type: :local` + The canonical name of the agent that produced this item. - Use a local computer environment. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:local` + The execution context that produced this tool call. - - `skills: Array[BetaLocalSkill]` + - `class Direct` - An optional list of skills. + - `type: :direct` - - `description: String` + The caller type. Always `direct`. - The description of the skill. + - `:direct` - - `name: String` + - `class Program` - The name of the skill. + - `caller_id: String` - - `path: String` + The call ID of the program item that produced this tool call. - The path to the directory containing the skill. + - `type: :program` - - `class BetaContainerReference` + The caller type. Always `program`. - - `container_id: String` + - `:program` - The ID of the referenced container. + - `created_by: String` - - `type: :container_reference` + The identifier of the actor that created the item. - References a container created with the /v1/containers endpoint + - `class AgentMessage` - - `:container_reference` + - `id: String` - - `class BetaCustomTool` + The unique ID of the agent 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) + - `author: String` - - `name: String` + The sending agent identity. - The name of the custom tool, used to identify it in tool calls. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `type: :custom` + Encrypted content sent between agents. - The type of the custom tool. Always `custom`. + - `class BetaResponseInputText` - - `:custom` + A text input to the model. - - `allowed_callers: Array[:direct | :programmatic]` + - `class BetaResponseOutputText` - The tool invocation context(s). + A text output from the model. - - `:direct` + - `class Text` - - `:programmatic` + A text content. - - `defer_loading: bool` + - `text: String` - Whether this tool should be deferred and discovered via tool search. + - `type: :text` - - `description: String` + - `:text` - Optional description of the custom tool, used to provide more context. + - `class SummaryText` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + A summary text from the model. - The input format for the custom tool. Default is unconstrained text. + - `text: String` - - `class Text` + A summary of the reasoning output from the model so far. - Unconstrained free-form text. + - `type: :summary_text` - - `type: :text` + The type of the object. Always `summary_text`. - Unconstrained text format. Always `text`. + - `:summary_text` + + - `class ReasoningText` - - `:text` + Reasoning text from the model. - - `class Grammar` + - `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 | :regex` + - `:reasoning_text` - The syntax of the grammar definition. One of `lark` or `regex`. + - `class BetaResponseOutputRefusal` - - `:lark` + A refusal from the model. - - `:regex` + - `class BetaResponseInputImage` - - `type: :grammar` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Grammar format. Always `grammar`. + - `class ComputerScreenshot` - - `:grammar` + A screenshot of a computer. - - `class BetaNamespaceTool` + - `detail: :low | :high | :auto | :original` - Groups function/custom tools under a shared namespace. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `description: String` + - `:low` - A description of the namespace shown to the model. + - `:high` - - `name: String` + - `:auto` - The namespace name used in tool calls (for example, `crm`). + - `:original` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `file_id: String` - The function/custom tools available inside this namespace. + The identifier of an uploaded file that contains the screenshot. - - `class Function` + - `image_url: String` - - `name: String` + The URL of the screenshot image. - - `type: :function` + - `type: :computer_screenshot` - - `:function` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:computer_screenshot` - The tool invocation context(s). + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: bool` + The breakpoint mode. Always `explicit`. - Whether this function should be deferred and discovered via tool search. + - `:explicit` - - `description: String` + - `class BetaResponseInputFile` - - `output_schema: Hash[Symbol, untyped]` + A file 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. + - `class EncryptedContent` - - `parameters: untyped` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `strict: bool` + - `encrypted_content: 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. + Opaque encrypted content. - - `class BetaCustomTool` + - `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`. - - `type: :namespace` + - `:encrypted_content` - The type of the tool. Always `namespace`. + - `recipient: String` - - `:namespace` + The destination agent identity. - - `class BetaToolSearchTool` + - `type: :agent_message` - Hosted or BYOT tool search configuration for deferred tools. + The type of the item. Always `agent_message`. - - `type: :tool_search` + - `:agent_message` - The type of the tool. Always `tool_search`. + - `agent: Agent{ agent_name}` - - `:tool_search` + The agent that produced this item. - - `description: 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: :server | :client` + - `class MultiAgentCall` - Whether tool search is executed by the server or by the client. + - `id: String` - - `:server` + The unique ID of the multi-agent call item. - - `:client` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `parameters: untyped` + The multi-agent action to execute. - Parameter schema for a client-executed tool search tool. + - `:spawn_agent` - - `class BetaWebSearchPreviewTool` + - `:interrupt_agent` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `:list_agents` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `:send_message` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `:followup_task` - - `:web_search_preview` + - `:wait_agent` - - `:web_search_preview_2025_03_11` + - `arguments: String` - - `search_content_types: Array[:text | :image]` + The JSON string of arguments generated for the action. - - `:text` + - `call_id: String` - - `:image` + The unique ID linking this call to its output. - - `search_context_size: :low | :medium | :high` + - `type: :multi_agent_call` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the multi-agent call. Always `multi_agent_call`. - - `:low` + - `:multi_agent_call` - - `:medium` + - `agent: Agent{ agent_name}` - - `:high` + The agent that produced this item. - - `user_location: UserLocation{ type, city, country, 2 more}` + - `agent_name: String` - The user's location. + The canonical name of the agent that produced this item. - - `type: :approximate` + - `class MultiAgentCallOutput` - The type of location approximation. Always `approximate`. + - `id: String` - - `:approximate` + The unique ID of the multi-agent call output item. - - `city: String` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - Free text input for the city of the user, e.g. `San Francisco`. + The multi-agent action that produced this result. - - `country: String` + - `:spawn_agent` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `:interrupt_agent` - - `region: String` + - `:list_agents` - Free text input for the region of the user, e.g. `California`. + - `:send_message` - - `timezone: String` + - `:followup_task` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:wait_agent` - - `class BetaApplyPatchTool` + - `call_id: String` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the multi-agent call. - - `type: :apply_patch` + - `output: Array[BetaResponseOutputText]` - The type of the tool. Always `apply_patch`. + Text output returned by the multi-agent action. - - `:apply_patch` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `allowed_callers: Array[:direct | :programmatic]` + The annotations of the text output. - The tool invocation context(s). + - `text: String` - - `:direct` + The text output from the model. - - `:programmatic` + - `type: :output_text` - - `type: :tool_search_output` + The type of the output text. Always `output_text`. - The item type. Always `tool_search_output`. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `:tool_search_output` + - `type: :multi_agent_call_output` - - `id: String` + The type of the multi-agent result. Always `multi_agent_call_output`. - The unique ID of this tool search output. + - `:multi_agent_call_output` - `agent: Agent{ agent_name}` @@ -96354,389 +107769,391 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` + - `class BetaResponseFunctionWebSearch` - The unique ID of the tool search call generated by the model. + 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. - - `execution: :server | :client` + - `id: String` - Whether tool search was executed by the server or by the client. + The unique ID of the web search tool call. - - `:server` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `:client` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `status: :in_progress | :completed | :incomplete` + - `class Search` - The status of the tool search output. + Action type "search" - Performs a web search query. - - `:in_progress` + - `type: :search` - - `:completed` + The action type. - - `:incomplete` + - `:search` - - `class AdditionalTools` + - `queries: Array[String]` - - `role: :developer` + The search queries. - The role that provided the additional tools. Only `developer` is supported. + - `query: String` - - `:developer` + The search query. - - `tools: Array[BetaTool]` + - `sources: Array[Source{ type, url}]` - A list of additional tools made available at this item. + The sources used in the search. - - `class BetaFunctionTool` + - `type: :url` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of source. Always `url`. - - `class BetaFileSearchTool` + - `: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). + - `url: String` - - `class BetaComputerTool` + 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). + - `class OpenPage` - - `class BetaComputerUsePreviewTool` + Action type "open_page" - Opens a specific URL from search results. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :open_page` - - `class BetaWebSearchTool` + The action 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). + - `:open_page` - - `class Mcp` + - `url: 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 URL opened by the model. - - `class CodeInterpreter` + - `class FindInPage` - A tool that runs Python code to help generate a response to a prompt. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `class ProgrammaticToolCalling` + - `pattern: String` - - `class ImageGeneration` + The pattern or text to search for within the page. - A tool that generates images using the GPT image models. + - `type: :find_in_page` - - `class LocalShell` + The action type. - A tool that allows the model to execute shell commands in a local environment. + - `:find_in_page` - - `class BetaFunctionShellTool` + - `url: String` - A tool that allows the model to execute shell commands. + The URL of the page searched for the pattern. - - `class BetaCustomTool` + - `status: :in_progress | :searching | :completed | :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 status of the web search tool call. - - `class BetaNamespaceTool` + - `:in_progress` - Groups function/custom tools under a shared namespace. + - `:searching` - - `class BetaToolSearchTool` + - `:completed` - Hosted or BYOT tool search configuration for deferred tools. + - `:failed` - - `class BetaWebSearchPreviewTool` + - `type: :web_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 web search tool call. Always `web_search_call`. - - `class BetaApplyPatchTool` + - `:web_search_call` - Allows the assistant to create, delete, or update files using unified diffs. + - `agent: Agent{ 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: String` + - `class BetaResponseComputerToolCall` - The unique ID of this additional tools item. + 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. - - `agent: Agent{ agent_name}` + - `id: String` - The agent that produced this item. + The unique ID of the computer call. - - `agent_name: String` + - `call_id: String` - The canonical name of the agent that produced this item. + An identifier used when responding to the tool call with output. - - `class BetaResponseReasoningItem` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - 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 pending safety checks for the computer call. - `id: String` - The unique identifier of the reasoning content. + The ID of the pending safety check. - - `summary: Array[Summary{ text, type}]` + - `code: String` - Reasoning summary content. + The type of the pending safety check. - - `text: String` + - `message: String` - A summary of the reasoning output from the model so far. + Details about the pending safety check. - - `type: :summary_text` + - `status: :in_progress | :completed | :incomplete` - The type of the object. Always `summary_text`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:summary_text` + - `:in_progress` - - `type: :reasoning` + - `:completed` - The type of the object. Always `reasoning`. + - `:incomplete` - - `:reasoning` + - `type: :computer_call` - - `agent: Agent{ agent_name}` + The type of the computer call. Always `computer_call`. - The agent that produced this item. + - `:computer_call` - - `agent_name: String` + - `action: BetaComputerAction` - The canonical name of the agent that produced this item. + A click action. - - `content: Array[Content{ text, type}]` + - `class Click` - Reasoning text content. + A click action. - - `text: String` + - `button: :left | :right | :wheel | 2 more` - The reasoning text from the model. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: :reasoning_text` + - `:left` - The type of the reasoning text. Always `reasoning_text`. + - `:right` - - `:reasoning_text` + - `:wheel` - - `encrypted_content: String` + - `:back` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `:forward` - - `status: :in_progress | :completed | :incomplete` + - `type: :click` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Specifies the event type. For a click action, this property is always `click`. - - `:in_progress` + - `:click` - - `:completed` + - `x: Integer` - - `:incomplete` + The x-coordinate where the click occurred. - - `class BetaResponseCompactionItemParam` + - `y_: Integer` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The y-coordinate where the click occurred. - - `encrypted_content: String` + - `keys: Array[String]` - The encrypted content of the compaction summary. + The keys being held while clicking. - - `type: :compaction` + - `class DoubleClick` - The type of the item. Always `compaction`. + A double click action. - - `:compaction` + - `keys: Array[String]` - - `id: String` + The keys being held while double-clicking. - The ID of the compaction item. + - `type: :double_click` - - `agent: Agent{ agent_name}` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The agent that produced this item. + - `:double_click` - - `agent_name: String` + - `x: Integer` - The canonical name of the agent that produced this item. + The x-coordinate where the double click occurred. - - `class ImageGenerationCall` + - `y_: Integer` - An image generation request made by the model. + The y-coordinate where the double click occurred. - - `id: String` + - `class Drag` - The unique ID of the image generation call. + A drag action. - - `result: String` + - `path: Array[Path{ x, y_}]` - The generated image encoded in base64. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `status: :in_progress | :completed | :generating | :failed` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The status of the image generation call. + - `x: Integer` - - `:in_progress` + The x-coordinate. - - `:completed` + - `y_: Integer` - - `:generating` + The y-coordinate. - - `:failed` + - `type: :drag` - - `type: :image_generation_call` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of the image generation call. Always `image_generation_call`. + - `:drag` - - `:image_generation_call` + - `keys: Array[String]` - - `agent: Agent{ agent_name}` + The keys being held while dragging the mouse. - The agent that produced this item. + - `class Keypress` - - `agent_name: String` + A collection of keypresses the model would like to perform. - The canonical name of the agent that produced this item. + - `keys: Array[String]` - - `class BetaResponseCodeInterpreterToolCall` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A tool call to run code. + - `type: :keypress` - - `id: String` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The unique ID of the code interpreter tool call. + - `:keypress` - - `code: String` + - `class Move` - The code to run, or null if not available. + A mouse move action. - - `container_id: String` + - `type: :move` - The ID of the container used to run the code. + Specifies the event type. For a move action, this property is always set to `move`. - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `:move` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `x: Integer` - - `class Logs` + The x-coordinate to move to. - The logs output from the code interpreter. + - `y_: Integer` - - `logs: String` + The y-coordinate to move to. - The logs output from the code interpreter. + - `keys: Array[String]` - - `type: :logs` + The keys being held while moving the mouse. - The type of the output. Always `logs`. + - `class Screenshot` - - `:logs` + A screenshot action. - - `class Image` + - `type: :screenshot` - The image output from the code interpreter. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: :image` + - `:screenshot` - The type of the output. Always `image`. + - `class Scroll` - - `:image` + A scroll action. - - `url: String` + - `scroll_x: Integer` - The URL of the image output from the code interpreter. + The horizontal scroll distance. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `scroll_y: Integer` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The vertical scroll distance. - - `:in_progress` + - `type: :scroll` - - `:completed` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `:incomplete` + - `:scroll` - - `:interpreting` + - `x: Integer` - - `:failed` + The x-coordinate where the scroll occurred. - - `type: :code_interpreter_call` + - `y_: Integer` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The y-coordinate where the scroll occurred. - - `:code_interpreter_call` + - `keys: Array[String]` - - `agent: Agent{ agent_name}` + The keys being held while scrolling. - The agent that produced this item. + - `class Type` - - `agent_name: String` + An action to type in text. - The canonical name of the agent that produced this item. + - `text: String` - - `class LocalShellCall` + The text to type. - A tool call to run a command on the local shell. + - `type: :type` - - `id: String` + Specifies the event type. For a type action, this property is always set to `type`. - The unique ID of the local shell call. + - `:type` - - `action: Action{ command, env, type, 3 more}` + - `class Wait` - Execute a shell command on the server. + A wait action. - - `command: Array[String]` + - `type: :wait` - The command to run. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `env: Hash[Symbol, String]` + - `:wait` - Environment variables to set for the command. + - `actions: BetaComputerActionList` - - `type: :exec` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the local shell action. Always `exec`. + - `class Click` - - `:exec` + A click action. - - `timeout_ms: Integer` + - `class DoubleClick` - Optional timeout in milliseconds for the command. + A double click action. - - `user: String` + - `class Drag` - Optional user to run the command as. + A drag action. - - `working_directory: String` + - `class Keypress` - Optional working directory to run the command in. + A collection of keypresses the model would like to perform. - - `call_id: String` + - `class Move` - The unique ID of the local shell tool call generated by the model. + A mouse move action. - - `status: :in_progress | :completed | :incomplete` + - `class Screenshot` - The status of the local shell call. + A screenshot action. - - `:in_progress` + - `class Scroll` - - `:completed` + A scroll action. - - `:incomplete` + - `class Type` - - `type: :local_shell_call` + An action to type in text. - The type of the local shell call. Always `local_shell_call`. + - `class Wait` - - `:local_shell_call` + A wait action. - `agent: Agent{ agent_name}` @@ -96746,75 +108163,70 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput` - - The output of a local shell tool call. + - `class BetaResponseComputerToolCallOutputItem` - `id: String` - The unique ID of the local shell tool call generated by the model. + The unique ID of the computer call tool output. - - `output: String` + - `call_id: String` - A JSON string of the output of the local shell tool call. + The ID of the computer tool call that produced the output. - - `type: :local_shell_call_output` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The type of the local shell tool call output. Always `local_shell_call_output`. + A computer screenshot image used with the computer use tool. - - `:local_shell_call_output` + - `type: :computer_screenshot` - - `agent: Agent{ 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: String` - The canonical name of the agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `status: :in_progress | :completed | :incomplete` + - `image_url: String` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The URL of the screenshot image. - - `:in_progress` + - `status: :completed | :incomplete | :failed | :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` - - `class ShellCall` - - A tool representing a request to execute one or more shell commands. - - - `action: Action{ commands, max_output_length, timeout_ms}` - - The shell commands and limits that describe how to run the tool call. - - - `commands: Array[String]` + - `:failed` - Ordered shell commands for the execution environment to run. + - `:in_progress` - - `max_output_length: Integer` + - `type: :computer_call_output` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The type of the computer tool call output. Always `computer_call_output`. - - `timeout_ms: Integer` + - `:computer_call_output` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `call_id: String` + The safety checks reported by the API that have been acknowledged by the + developer. - The unique ID of the shell tool call generated by the model. + - `id: String` - - `type: :shell_call` + The ID of the pending safety check. - The type of the item. Always `shell_call`. + - `code: String` - - `:shell_call` + The type of the pending safety check. - - `id: String` + - `message: String` - The unique ID of the shell tool call. Populated when this item is returned via API. + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -96824,105 +108236,102 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. + - `created_by: String` - - `:direct` + The identifier of the actor that created the item. - - `class Program` + - `class BetaResponseReasoningItem` - - `caller_id: 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). - The call ID of the program item that produced this tool call. + - `id: String` - - `type: :program` + The unique identifier of the reasoning content. - The caller type. Always `program`. + - `summary: Array[Summary{ text, type}]` - - `:program` + Reasoning summary content. - - `environment: BetaLocalEnvironment | BetaContainerReference` + - `text: String` - The environment to execute the shell commands in. + A summary of the reasoning output from the model so far. - - `class BetaLocalEnvironment` + - `type: :summary_text` - - `class BetaContainerReference` + The type of the object. Always `summary_text`. - - `status: :in_progress | :completed | :incomplete` + - `:summary_text` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `type: :reasoning` - - `:in_progress` + The type of the object. Always `reasoning`. - - `:completed` + - `:reasoning` - - `:incomplete` + - `agent: Agent{ agent_name}` - - `class ShellCallOutput` + The agent that produced this item. - The streamed output items emitted by a shell tool call. + - `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. + - `content: Array[Content{ text, type}]` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + Reasoning text content. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `text: String` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + The reasoning text from the model. - The exit or timeout outcome associated with this shell call. + - `type: :reasoning_text` - - `class Timeout` + The type of the reasoning text. Always `reasoning_text`. - Indicates that the shell call exceeded its configured time limit. + - `:reasoning_text` - - `type: :timeout` + - `encrypted_content: String` - The outcome type. Always `timeout`. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `:timeout` + - `status: :in_progress | :completed | :incomplete` - - `class Exit` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Indicates that the shell commands finished and returned an exit code. + - `:in_progress` - - `exit_code: Integer` + - `:completed` - The exit code returned by the shell process. + - `:incomplete` - - `type: :exit` + - `class Program` - The outcome type. Always `exit`. + - `id: String` - - `:exit` + The unique ID of the program item. - - `stderr: String` + - `call_id: String` - Captured stderr output for the shell call. + The stable call ID of the program item. - - `stdout: String` + - `code: String` - Captured stdout output for the shell call. + The JavaScript source executed by programmatic tool calling. - - `type: :shell_call_output` + - `fingerprint: String` - The type of the item. Always `shell_call_output`. + Opaque program replay fingerprint that must be round-tripped. - - `:shell_call_output` + - `type: :program` - - `id: String` + The type of the item. Always `program`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `:program` - `agent: Agent{ agent_name}` @@ -96932,1354 +108341,1361 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class ProgramOutput` - The execution context that produced this tool call. + - `id: String` - - `class Direct` + The unique ID of the program output item. - - `type: :direct` + - `call_id: String` - The caller type. Always `direct`. + The call ID of the program item. - - `:direct` + - `result: String` - - `class Program` + The result produced by the program item. - - `caller_id: String` + - `status: :completed | :incomplete` - The call ID of the program item that produced this tool call. + The terminal status of the program output item. - - `type: :program` + - `:completed` - The caller type. Always `program`. + - `:incomplete` - - `:program` + - `type: :program_output` - - `max_output_length: Integer` + The type of the item. Always `program_output`. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `:program_output` - - `status: :in_progress | :completed | :incomplete` + - `agent: Agent{ agent_name}` - The status of the shell call output. + The agent that produced this item. - - `:in_progress` + - `agent_name: String` - - `:completed` + The canonical name of the agent that produced this item. - - `:incomplete` + - `class BetaResponseToolSearchCall` - - `class ApplyPatchCall` + - `id: String` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the tool search call item. + + - `arguments: untyped` + + Arguments used for the tool search call. - `call_id: String` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the tool search call generated by the model. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `execution: :server | :client` - The specific create, delete, or update instruction for the apply_patch tool call. + Whether tool search was executed by the server or by the client. - - `class CreateFile` + - `:server` - Instruction for creating a new file via the apply_patch tool. + - `:client` - - `diff: String` + - `status: :in_progress | :completed | :incomplete` - Unified diff content to apply when creating the file. + The status of the tool search call item that was recorded. - - `path: String` + - `:in_progress` - Path of the file to create relative to the workspace root. + - `:completed` - - `type: :create_file` + - `:incomplete` - The operation type. Always `create_file`. + - `type: :tool_search_call` - - `:create_file` + The type of the item. Always `tool_search_call`. - - `class DeleteFile` + - `:tool_search_call` - Instruction for deleting an existing file via the apply_patch tool. + - `agent: Agent{ agent_name}` - - `path: String` + The agent that produced this item. - Path of the file to delete relative to the workspace root. + - `agent_name: String` - - `type: :delete_file` + The canonical name of the agent that produced this item. - The operation type. Always `delete_file`. + - `created_by: String` - - `:delete_file` + The identifier of the actor that created the item. - - `class UpdateFile` + - `class BetaResponseToolSearchOutputItem` - Instruction for updating an existing file via the apply_patch tool. + - `id: String` - - `diff: String` + The unique ID of the tool search output item. - Unified diff content to apply to the existing file. + - `call_id: String` - - `path: String` + The unique ID of the tool search call generated by the model. - Path of the file to update relative to the workspace root. + - `execution: :server | :client` - - `type: :update_file` + Whether tool search was executed by the server or by the client. - The operation type. Always `update_file`. + - `:server` - - `:update_file` + - `:client` - - `status: :in_progress | :completed` + - `status: :in_progress | :completed | :incomplete` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the tool search output item that was recorded. - `:in_progress` - `:completed` - - `type: :apply_patch_call` - - The type of the item. Always `apply_patch_call`. - - - `:apply_patch_call` - - - `id: String` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. + - `:incomplete` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `tools: Array[BetaTool]` - The execution context that produced this tool call. + The loaded tool definitions returned by tool search. - - `class Direct` + - `class BetaFunctionTool` - - `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). - The caller type. Always `direct`. + - `name: String` - - `:direct` + The name of the function to call. - - `class Program` + - `parameters: Hash[Symbol, untyped]` - - `caller_id: String` + A JSON schema object describing the parameters of the function. - The call ID of the program item that produced this tool call. + - `strict: bool` - - `type: :program` + Whether strict parameter validation is enforced for this function tool. - The caller type. Always `program`. + - `type: :function` - - `:program` + The type of the function tool. Always `function`. - - `class ApplyPatchCallOutput` + - `:function` - The streamed output emitted by an apply patch tool call. + - `allowed_callers: Array[:direct | :programmatic]` - - `call_id: String` + The tool invocation context(s). - The unique ID of the apply patch tool call generated by the model. + - `:direct` - - `status: :completed | :failed` + - `:programmatic` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `defer_loading: bool` - - `:completed` + Whether this function is deferred and loaded via tool search. - - `:failed` + - `description: String` - - `type: :apply_patch_call_output` + A description of the function. Used by the model to determine whether or not to call the function. - The type of the item. Always `apply_patch_call_output`. + - `output_schema: Hash[Symbol, untyped]` - - `:apply_patch_call_output` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `id: String` + - `class BetaFileSearchTool` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + 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: Agent{ 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[String]` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The IDs of the vector stores to search. - The execution context that produced this tool call. + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `class Direct` + A filter to apply. - - `type: :direct` + - `class ComparisonFilter` - The caller type. Always `direct`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:direct` + - `key: String` - - `class Program` + The key to compare against the value. - - `caller_id: String` + - `type: :eq | :ne | :gt | 5 more` - The call ID of the program item that produced this tool call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: :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 - The caller type. Always `program`. + - `:eq` - - `:program` + - `:ne` - - `output: String` + - `:gt` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `:gte` - - `class McpListTools` + - `:lt` - A list of tools available on an MCP server. + - `:lte` - - `id: String` + - `:in` - The unique ID of the list. + - `:nin` - - `server_label: String` + - `value: String | Float | bool | Array[String | Float]` - The label of the MCP server. + The value to compare against the attribute key; supports string, number, or boolean types. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `String = String` - The tools available on the server. + - `Float = Float` - - `input_schema: untyped` + - `UnionMember2 = bool` - The JSON schema describing the tool's input. + - `UnionMember3 = Array[String | Float]` - - `name: String` + - `String = String` - The name of the tool. + - `Float = Float` - - `annotations: untyped` + - `class CompoundFilter` - Additional annotations about the tool. + Combine multiple filters using `and` or `or`. - - `description: String` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - The description of the tool. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: :mcp_list_tools` + - `class ComparisonFilter` - 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: Agent{ agent_name}` + The key to compare against the value. - The agent that produced this item. + - `type: :eq | :ne | :gt | 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: String` + - `:eq` - Error message if the server could not list tools. + - `:ne` - - `class McpApprovalRequest` + - `: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 | Float | bool | Array[String | Float]` - 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 = String` - The label of the MCP server making the request. + - `Float = Float` - - `type: :mcp_approval_request` + - `UnionMember2 = bool` - The type of the item. Always `mcp_approval_request`. + - `UnionMember3 = Array[String | Float]` - - `:mcp_approval_request` + - `String = String` - - `agent: Agent{ agent_name}` + - `Float = Float` - The agent that produced this item. + - `UnionMember1 = untyped` - - `agent_name: String` + - `type: :and | :or` - The canonical name of the agent that produced this item. + Type of operation: `and` or `or`. - - `class McpApprovalResponse` + - `:and` - A response to an MCP approval request. + - `:or` - - `approval_request_id: String` + - `max_num_results: Integer` - The ID of the approval request being answered. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `approve: bool` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - Whether the request was approved. + Ranking options for search. - - `type: :mcp_approval_response` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - The type of the item. Always `mcp_approval_response`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `:mcp_approval_response` + - `embedding_weight: Float` - - `id: String` + The weight of the embedding in the reciprocal ranking fusion. - The unique ID of the approval response + - `text_weight: Float` - - `agent: Agent{ agent_name}` + The weight of the text in the reciprocal ranking fusion. - The agent that produced this item. + - `ranker: :auto | :"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` - - `reason: String` + - `:"default-2024-11-15"` - Optional reason for the decision. + - `score_threshold: Float` - - `class McpCall` + 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 invocation of a tool on an MCP server. + - `class BetaComputerTool` - - `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 tool call. + - `type: :computer` - - `arguments: String` + The type of the computer tool. Always `computer`. - A JSON string of the arguments passed to the tool. + - `:computer` - - `name: String` + - `class BetaComputerUsePreviewTool` - The name of the tool that was run. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `server_label: String` + - `display_height: Integer` - The label of the MCP server running the tool. + The height of the computer display. - - `type: :mcp_call` + - `display_width: Integer` - The type of the item. Always `mcp_call`. + The width of the computer display. - - `:mcp_call` + - `environment: :windows | :mac | :linux | 2 more` - - `agent: Agent{ agent_name}` + The type of computer environment to control. - The agent that produced this item. + - `:windows` - - `agent_name: String` + - `:mac` - The canonical name of the agent that produced this item. + - `:linux` - - `approval_request_id: String` + - `:ubuntu` - 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. + - `:browser` - - `error: String` + - `type: :computer_use_preview` - The error from the tool call, if any. + The type of the computer use tool. Always `computer_use_preview`. - - `output: String` + - `:computer_use_preview` - The output from the tool call. + - `class BetaWebSearchTool` - - `status: :in_progress | :completed | :incomplete | 2 more` + 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 status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `type: :web_search | :web_search_2025_08_26` - - `:in_progress` + 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` - - `:calling` + - `filters: Filters{ allowed_domains}` - - `:failed` + Filters for the search. - - `class BetaResponseCustomToolCallOutput` + - `allowed_domains: Array[String]` - The output of a custom tool call from your code, being sent back to the model. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `call_id: String` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The call ID, used to map this custom tool call output to a custom tool call. + - `search_context_size: :low | :medium | :high` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + High 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 output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `:low` - - `String = String` + - `:medium` - A string of the output of the custom tool call. + - `:high` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `user_location: UserLocation{ city, country, region, 2 more}` - Text, image, or file output of the custom tool call. + The approximate location of the user. - - `class BetaResponseInputText` + - `city: String` - A text input to the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `class BetaResponseInputImage` + - `country: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class BetaResponseInputFile` + - `region: String` - A file input to the model. + Free text input for the region of the user, e.g. `California`. - - `type: :custom_tool_call_output` + - `timezone: String` - The type of the custom tool call output. Always `custom_tool_call_output`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:custom_tool_call_output` + - `type: :approximate` - - `id: String` + The type of location approximation. Always `approximate`. - The unique ID of the custom tool call output in the OpenAI platform. + - `:approximate` - - `agent: Agent{ agent_name}` + - `class Mcp` - The agent that produced this item. + 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_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_: Direct{ type} | Program{ caller_id, type}` + - `type: :mcp` - The execution context that produced this tool call. + The type of the MCP tool. Always `mcp`. - - `class Direct` + - `:mcp` - - `type: :direct` + - `allowed_callers: Array[:direct | :programmatic]` - The caller type. Always `direct`. + The tool invocation context(s). - `:direct` - - `class Program` + - `:programmatic` - - `caller_id: String` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - The call ID of the program item that produced this tool call. + List of allowed tool names or a filter object. - - `type: :program` + - `McpAllowedTools = Array[String]` - The caller type. Always `program`. + A string array of allowed tool names - - `:program` + - `class McpToolFilter` - - `class BetaResponseCustomToolCall` + A filter object to specify which tools are allowed. - A call to a custom tool created by the model. + - `read_only: bool` - - `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. - An identifier used to map this custom tool call to a tool call output. + - `tool_names: Array[String]` - - `input: String` + List of allowed tool names. - The input for the custom tool call generated by the model. + - `authorization: String` - - `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 name of the custom tool being called. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `type: :custom_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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The type of the custom tool call. Always `custom_tool_call`. + Currently supported `connector_id` values are: - - `:custom_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` - - `id: String` + - `:connector_dropbox` - The unique ID of the custom tool call in the OpenAI platform. + - `:connector_gmail` - - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `:connector_outlookemail` - The execution context that produced this tool call. + - `:connector_sharepoint` - - `class Direct` + - `defer_loading: bool` - - `type: :direct` + Whether this MCP tool is deferred and discovered via tool search. - - `:direct` + - `headers: Hash[Symbol, String]` - - `class Program` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `caller_id: String` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :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` + - `class McpToolApprovalFilter` - - `: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. - - `namespace: String` + - `always: Always{ read_only, tool_names}` - The namespace of the custom tool being called. + A filter object to specify which tools are allowed. - - `class CompactionTrigger` + - `read_only: bool` - Compacts the current context. Must be the final input 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. - - `type: :compaction_trigger` + - `tool_names: Array[String]` - The type of the item. Always `compaction_trigger`. + List of allowed tool names. - - `:compaction_trigger` + - `never: Never{ read_only, tool_names}` - - `agent: Agent{ agent_name}` + A filter object to specify which tools are allowed. - The agent that produced this item. + - `read_only: bool` - - `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: Array[String]` - - `class ItemReference` + List of allowed tool names. - An internal identifier for an item to reference. + - `McpToolApprovalSetting = :always | :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 item to reference. + - `:always` - - `agent: Agent{ agent_name}` + - `:never` - The agent that produced this item. + - `server_description: String` - - `agent_name: String` + Optional description of the MCP server, used to provide more context. - The canonical name of the agent that produced this item. + - `server_url: String` - - `type: :item_reference` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The type of item to reference. Always `item_reference`. + - `tunnel_id: String` - - `:item_reference` + 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. - - `class Program` + - `class CodeInterpreter` - - `id: String` + A tool that runs Python code to help generate a response to a prompt. - The unique ID of this program item. + - `container: String | CodeInterpreterToolAuto{ 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 stable call ID of the program item. + - `String = String` - - `code: String` + The container ID. - The JavaScript source executed by programmatic tool calling. + - `class CodeInterpreterToolAuto` - - `fingerprint: String` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Opaque program replay fingerprint that must be round-tripped. + - `type: :auto` - - `type: :program` + Always `auto`. - The item type. Always `program`. + - `:auto` - - `:program` + - `file_ids: Array[String]` - - `agent: Agent{ agent_name}` + An optional list of uploaded files to make available to your code. - The agent that produced this item. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `agent_name: String` + The memory limit for the code interpreter container. - The canonical name of the agent that produced this item. + - `:"1g"` - - `class ProgramOutput` + - `:"4g"` - - `id: String` + - `:"16g"` - The unique ID of this program output item. + - `:"64g"` - - `call_id: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The call ID of the program item. + Network access policy for the container. - - `result: String` + - `class BetaContainerNetworkPolicyDisabled` - The result produced by the program item. + - `type: :disabled` - - `status: :completed | :incomplete` + Disable outbound network access. Always `disabled`. - The terminal status of the program output. + - `:disabled` - - `:completed` + - `class BetaContainerNetworkPolicyAllowlist` - - `:incomplete` + - `allowed_domains: Array[String]` - - `type: :program_output` + A list of allowed domains when type is `allowlist`. - The item type. Always `program_output`. + - `type: :allowlist` - - `:program_output` + Allow outbound network access only to specified domains. Always `allowlist`. - - `agent: Agent{ agent_name}` + - `:allowlist` - The agent that produced this item. + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `agent_name: String` + Optional domain-scoped secrets for allowlisted domains. - The canonical name of the agent that produced this item. + - `domain: String` -### Beta Response Input Audio + The domain associated with the secret. -- `class BetaResponseInputAudio` + - `name: String` - An audio input to the model. + The name of the secret to inject for the domain. - - `input_audio: InputAudio{ data, format_}` + - `value: String` - - `data: String` + The secret value to inject for the domain. - Base64-encoded audio data. + - `type: :code_interpreter` - - `format_: :mp3 | :wav` + The type of the code interpreter tool. Always `code_interpreter`. - The format of the audio data. Currently supported formats are `mp3` and - `wav`. + - `:code_interpreter` - - `:mp3` + - `allowed_callers: Array[:direct | :programmatic]` - - `:wav` + The tool invocation context(s). - - `type: :input_audio` + - `:direct` - The type of the input item. Always `input_audio`. + - `:programmatic` - - `:input_audio` + - `class ProgrammaticToolCalling` -### Beta Response Input Content + - `type: :programmatic_tool_calling` -- `BetaResponseInputContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile` + The type of the tool. Always `programmatic_tool_calling`. - A text input to the model. + - `:programmatic_tool_calling` - - `class BetaResponseInputText` + - `class ImageGeneration` - A text input to the model. + A tool that generates images using the GPT image models. - - `text: String` + - `type: :image_generation` - The text input to the model. + The type of the image generation tool. Always `image_generation`. - - `type: :input_text` + - `:image_generation` - The type of the input item. Always `input_text`. + - `action: :generate | :edit | :auto` - - `:input_text` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: :transparent | :opaque | :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. - - `class BetaResponseInputImage` + `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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `detail: :low | :high | :auto | :original` + - `:transparent` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:opaque` - - `:low` + - `:auto` - - `:high` + - `input_fidelity: :high | :low` - - `: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`. - - `:original` + - `:high` - - `type: :input_image` + - `:low` - The type of the input item. Always `input_image`. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `:input_image` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - `file_id: String` - The ID of the file to be sent to the model. + File ID for the mask image. - `image_url: String` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Base64-encoded mask image. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. + The image generation model to use. Default: `gpt-image-1`. - - `mode: :explicit` + - `String = String` - The breakpoint mode. Always `explicit`. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:explicit` + The image generation model to use. Default: `gpt-image-1`. - - `class BetaResponseInputFile` + - `:"gpt-image-1"` - A file input to the model. + - `:"gpt-image-1-mini"` - - `type: :input_file` + - `:"gpt-image-2"` - The type of the input item. Always `input_file`. + - `:"gpt-image-2-2026-04-21"` - - `:input_file` + - `:"gpt-image-1.5"` - - `detail: :auto | :low | :high` + - `:"chatgpt-image-latest"` - 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`. + - `moderation: :auto | :low` + + Moderation level for the generated image. Default: `auto`. - `:auto` - `:low` - - `:high` - - - `file_data: String` - - The content of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. + - `output_compression: Integer` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Compression level for the output image. Default: 100. - Marks the exact end of a reusable 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_format: :png | :webp | :jpeg` - - `mode: :explicit` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The breakpoint mode. Always `explicit`. + - `:png` - - `:explicit` + - `:webp` -### Beta Response Input File + - `:jpeg` -- `class BetaResponseInputFile` + - `partial_images: Integer` - A file input to the model. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: :input_file` + - `quality: :low | :medium | :high | :auto` - The type of the input item. Always `input_file`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `:input_file` + - `:low` - - `detail: :auto | :low | :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` - - `:low` - - - `:high` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `file_data: 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 content of the file to be sent to the model. + - `String = String` - - `file_id: String` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - The ID of the file to be sent 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`. - - `file_url: String` + - `:"1024x1024"` - The URL of the file to be sent to the model. + - `:"1024x1536"` - - `filename: String` + - `:"1536x1024"` - The name of the file to be sent to the model. + - `:auto` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class LocalShell` - Marks the exact end of a reusable 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 that allows the model to execute shell commands in a local environment. - - `mode: :explicit` + - `type: :local_shell` - The breakpoint mode. Always `explicit`. + The type of the local shell tool. Always `local_shell`. - - `:explicit` + - `:local_shell` -### Beta Response Input File Content + - `class BetaFunctionShellTool` -- `class BetaResponseInputFileContent` + A tool that allows the model to execute shell commands. - A file input to the model. + - `type: :shell` - - `type: :input_file` + The type of the shell tool. Always `shell`. - The type of the input item. Always `input_file`. + - `:shell` - - `:input_file` + - `allowed_callers: Array[:direct | :programmatic]` - - `detail: :auto | :low | :high` + The tool invocation context(s). - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `:direct` - - `:auto` + - `:programmatic` - - `:low` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `:high` + - `class BetaContainerAuto` - - `file_data: String` + - `type: :container_auto` - The base64-encoded data of the file to be sent to the model. + Automatically creates a container for this request - - `file_id: String` + - `:container_auto` - The ID of the file to be sent to the model. + - `file_ids: Array[String]` - - `file_url: String` + An optional list of uploaded files to make available to your code. - The URL of the file to be sent to the model. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `filename: String` + The memory limit for the container. - The name of the file to be sent to the model. + - `:"1g"` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:explicit` + Network access policy for the container. -### Beta Response Input Image + - `class BetaContainerNetworkPolicyDisabled` -- `class BetaResponseInputImage` + - `class BetaContainerNetworkPolicyAllowlist` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `detail: :low | :high | :auto | :original` + An optional list of skills referenced by id or inline data. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class BetaSkillReference` - - `:low` + - `skill_id: String` - - `:high` + The ID of the referenced skill. - - `:auto` + - `type: :skill_reference` - - `:original` + References a skill created with the /v1/skills endpoint. - - `type: :input_image` + - `:skill_reference` - The type of the input item. Always `input_image`. + - `version: String` - - `:input_image` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `file_id: String` + - `class BetaInlineSkill` - The ID of the file to be sent to the model. + - `description: String` - - `image_url: String` + The description of the skill. - 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: PromptCacheBreakpoint{ mode}` + The name of the skill. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `source: BetaInlineSkillSource` - - `mode: :explicit` + Inline skill payload - The breakpoint mode. Always `explicit`. + - `data: String` - - `:explicit` + Base64-encoded skill zip bundle. -### Beta Response Input Image Content + - `media_type: :"application/zip"` -- `class BetaResponseInputImageContent` + The media type of the inline skill payload. Must be `application/zip`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:"application/zip"` - - `type: :input_image` + - `type: :base64` - The type of the input item. Always `input_image`. + The type of the inline skill source. Must be `base64`. - - `:input_image` + - `:base64` - - `detail: :low | :high | :auto | :original` + - `type: :inline` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Defines an inline skill for this request. - - `:low` + - `:inline` - - `:high` + - `class BetaLocalEnvironment` - - `:auto` + - `type: :local` - - `:original` + Use a local computer environment. - - `file_id: String` + - `:local` - The ID of the file to be sent to the model. + - `skills: Array[BetaLocalSkill]` - - `image_url: String` + An optional list of skills. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `description: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The description of the skill. - Marks the exact end of a reusable 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 skill. - The breakpoint mode. Always `explicit`. + - `path: String` - - `:explicit` + The path to the directory containing the skill. -### Beta Response Input Item + - `class BetaContainerReference` -- `BetaResponseInputItem = BetaEasyInputMessage | Message{ content, role, agent, 2 more} | BetaResponseOutputMessage | 32 more` + - `container_id: String` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The ID of the referenced container. - - `class BetaEasyInputMessage` + - `type: :container_reference` - 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. + References a container created with the /v1/containers endpoint - - `content: String | BetaResponseInputMessageContentList` + - `:container_reference` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `class BetaCustomTool` - - `String = 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 text input to the model. + - `name: String` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + The name of the custom tool, used to identify it in tool calls. - A list of one or many input items to the model, containing different content - types. + - `type: :custom` - - `class BetaResponseInputText` + The type of the custom tool. Always `custom`. - A text input to the model. + - `:custom` - - `text: String` + - `allowed_callers: Array[:direct | :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: bool` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: String` - - `mode: :explicit` + Optional description of the custom tool, used to provide more context. - The breakpoint mode. Always `explicit`. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `:explicit` + The input format for the custom tool. Default is unconstrained text. - - `class BetaResponseInputImage` + - `class Text` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Unconstrained free-form text. - - `detail: :low | :high | :auto | :original` + - `type: :text` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Unconstrained text format. Always `text`. - - `:low` + - `:text` - - `:high` + - `class Grammar` - - `:auto` + A grammar defined by the user. - - `:original` + - `definition: String` - - `type: :input_image` + The grammar definition. - The type of the input item. Always `input_image`. + - `syntax: :lark | :regex` - - `:input_image` + The syntax of the grammar definition. One of `lark` or `regex`. - - `file_id: String` + - `:lark` - The ID of the file to be sent to the model. + - `:regex` - - `image_url: 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: PromptCacheBreakpoint{ 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. + - `class BetaNamespaceTool` - - `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. - - `class BetaResponseInputFile` + - `name: String` - A file input to the model. + The namespace name used in tool calls (for example, `crm`). - - `type: :input_file` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - The type of the input item. Always `input_file`. + The function/custom tools available inside this namespace. - - `:input_file` + - `class Function` - - `detail: :auto | :low | :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: Array[:direct | :programmatic]` - - `:high` + The tool invocation context(s). - - `file_data: String` + - `:direct` - The content of the file to be sent to the model. + - `:programmatic` - - `file_id: String` + - `defer_loading: bool` - The ID of the file to be sent to the model. + Whether this function should be deferred and discovered via tool search. - - `file_url: String` + - `description: String` - The URL of the file to be sent to the model. + - `output_schema: Hash[Symbol, untyped]` - - `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 name of the file to be sent to the model. + - `parameters: untyped` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `strict: bool` - Marks the exact end of a reusable 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` + - `class BetaCustomTool` - 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` + - `type: :namespace` - - `role: :user | :assistant | :system | :developer` + The type of the tool. Always `namespace`. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `:namespace` - - `:user` + - `class BetaToolSearchTool` - - `:assistant` + Hosted or BYOT tool search configuration for deferred tools. - - `:system` + - `type: :tool_search` - - `:developer` + The type of the tool. Always `tool_search`. - - `phase: :commentary` + - `:tool_search` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `description: String` - - `:commentary` + Description shown to the model for a client-executed tool search tool. - - `type: :message` + - `execution: :server | :client` - The type of the message input. Always `message`. + Whether tool search is executed by the server or by the client. - - `:message` + - `:server` - - `class Message` + - `:client` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `parameters: untyped` - - `content: BetaResponseInputMessageContentList` + Parameter schema for a client-executed tool search tool. - A list of one or many input items to the model, containing different content - types. + - `class BetaWebSearchPreviewTool` - - `role: :user | :system | :developer` + 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 role of the message input. One of `user`, `system`, or `developer`. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `:user` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `:system` + - `:web_search_preview` - - `:developer` + - `:web_search_preview_2025_03_11` - - `agent: Agent{ agent_name}` + - `search_content_types: Array[:text | :image]` - The agent that produced this item. + - `:text` - - `agent_name: String` + - `:image` - The canonical name of the agent that produced this item. + - `search_context_size: :low | :medium | :high` - - `status: :in_progress | :completed | :incomplete` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:low` - - `:in_progress` + - `:medium` - - `:completed` + - `:high` - - `:incomplete` + - `user_location: UserLocation{ type, city, country, 2 more}` - - `type: :message` + The user's location. - The type of the message input. Always set to `message`. + - `type: :approximate` - - `:message` + The type of location approximation. Always `approximate`. - - `class BetaResponseOutputMessage` + - `:approximate` - An output message from the model. + - `city: String` - - `id: String` + Free text input for the city of the user, e.g. `San Francisco`. - The unique ID of the output message. + - `country: String` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The content of the output message. + - `region: String` - - `class BetaResponseOutputText` + Free text input for the region of the user, e.g. `California`. - A text output from the model. + - `timezone: String` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The annotations of the text output. + - `class BetaApplyPatchTool` - - `class FileCitation` + Allows the assistant to create, delete, or update files using unified diffs. - A citation to a file. + - `type: :apply_patch` - - `file_id: String` + The type of the tool. Always `apply_patch`. - The ID of the file. + - `:apply_patch` - - `filename: String` + - `allowed_callers: Array[:direct | :programmatic]` - The filename of the file cited. + The tool invocation context(s). - - `index: Integer` + - `:direct` - The index of the file in the list of files. + - `:programmatic` - - `type: :file_citation` + - `type: :tool_search_output` - The type of the file citation. Always `file_citation`. + The type of the item. Always `tool_search_output`. - - `:file_citation` + - `:tool_search_output` - - `class URLCitation` + - `agent: Agent{ agent_name}` - A citation for a web resource used to generate a model response. + The agent that produced this item. - - `end_index: Integer` + - `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: Integer` + - `created_by: String` - The index of the first character of the URL citation in the message. + The identifier of the actor that created the item. - - `title: String` + - `class AdditionalTools` - The title of the web resource. + - `id: String` - - `type: :url_citation` + The unique ID of the additional tools item. - The type of the URL citation. Always `url_citation`. + - `role: :unknown | :user | :assistant | 5 more` - - `:url_citation` + The role that provided the additional tools. - - `url: String` + - `:unknown` - The URL of the web resource. + - `:user` - - `class ContainerFileCitation` + - `:assistant` - A citation for a container file used to generate a model response. + - `:system` - - `container_id: String` + - `:critic` - The ID of the container file. + - `:discriminator` - - `end_index: Integer` + - `:developer` - The index of the last character of the container file citation in the message. + - `:tool` - - `file_id: String` + - `tools: Array[BetaTool]` - The ID of the file. + The additional tool definitions made available at this item. - - `filename: String` + - `class BetaFunctionTool` - The filename of the container file cited. + 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). - - `start_index: Integer` + - `class BetaFileSearchTool` - The index of the first character of the container file citation in the message. + 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: :container_file_citation` + - `class BetaComputerTool` - The type of the container file citation. Always `container_file_citation`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:container_file_citation` + - `class BetaComputerUsePreviewTool` - - `class FilePath` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A path to a file. + - `class BetaWebSearchTool` - - `file_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 ID of the file. + - `class Mcp` - - `index: Integer` + 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 file in the list of files. + - `class CodeInterpreter` - - `type: :file_path` + A tool that runs Python code to help generate a response to a prompt. - The type of the file path. Always `file_path`. + - `class ProgrammaticToolCalling` - - `:file_path` + - `class ImageGeneration` - - `text: String` + A tool that generates images using the GPT image models. - The text output from the model. + - `class LocalShell` - - `type: :output_text` + A tool that allows the model to execute shell commands in a local environment. - The type of the output text. Always `output_text`. + - `class BetaFunctionShellTool` - - `:output_text` + A tool that allows the model to execute shell commands. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `class BetaCustomTool` - - `token: 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) - - `bytes: Array[Integer]` + - `class BetaNamespaceTool` - - `logprob: Float` + Groups function/custom tools under a shared namespace. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `class BetaToolSearchTool` - - `token: String` + Hosted or BYOT tool search configuration for deferred tools. - - `bytes: Array[Integer]` + - `class BetaWebSearchPreviewTool` - - `logprob: Float` + 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). - - `class BetaResponseOutputRefusal` + - `class BetaApplyPatchTool` - A refusal from the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `refusal: String` + - `type: :additional_tools` - The refusal explanation from the model. + The type of the item. Always `additional_tools`. - - `type: :refusal` + - `:additional_tools` - The type of the refusal. Always `refusal`. + - `agent: Agent{ agent_name}` - - `:refusal` + The agent that produced this item. - - `role: :assistant` + - `agent_name: String` - The role of the output message. Always `assistant`. + The canonical name of the agent that produced this item. - - `:assistant` + - `class BetaResponseCompactionItem` - - `status: :in_progress | :completed | :incomplete` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - 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 compaction item. - - `:completed` + - `encrypted_content: String` - - `:incomplete` + The encrypted content that was produced by compaction. - - `type: :message` + - `type: :compaction` - The type of the output message. Always `message`. + The type of the item. Always `compaction`. - - `:message` + - `:compaction` - `agent: Agent{ agent_name}` @@ -98289,47 +109705,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` - - 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. + - `created_by: String` - - `:commentary` + The identifier of the actor that created the item. - - `class BetaResponseFileSearchToolCall` + - `class ImageGenerationCall` - 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. + An image generation request made by the model. - `id: String` - The unique ID of the file search tool call. + The unique ID of the image generation call. - - `queries: Array[String]` + - `result: String` - The queries used to search for files. + The generated image encoded in base64. - - `status: :in_progress | :searching | :completed | 2 more` + - `status: :in_progress | :completed | :generating | :failed` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the image generation call. - `:in_progress` - - `:searching` - - `:completed` - - `:incomplete` + - `:generating` - `:failed` - - `type: :file_search_call` + - `type: :image_generation_call` - The type of the file search tool call. Always `file_search_call`. + The type of the image generation call. Always `image_generation_call`. - - `:file_search_call` + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -98339,73 +109747,58 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - The results of the file search tool call. - - - `attributes: Hash[Symbol, String | Float | bool]` - - Set of 16 key-value pairs that can be attached to an object. 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 = String` - - - `Float = Float` + - `class BetaResponseCodeInterpreterToolCall` - - `UnionMember2 = bool` + A tool call to run code. - - `file_id: String` + - `id: String` - The unique ID of the file. + The unique ID of the code interpreter tool call. - - `filename: String` + - `code: String` - The name of the file. + The code to run, or null if not available. - - `score: Float` + - `container_id: String` - The relevance score of the file - a value between 0 and 1. + The ID of the container used to run the code. - - `text: String` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - The text that was retrieved from the file. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `class BetaResponseComputerToolCall` + - `class Logs` - 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 logs output from the code interpreter. - - `id: String` + - `logs: String` - The unique ID of the computer call. + The logs output from the code interpreter. - - `call_id: String` + - `type: :logs` - An identifier used when responding to the tool call with output. + The type of the output. Always `logs`. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `:logs` - The pending safety checks for the computer call. + - `class Image` - - `id: String` + The image output from the code interpreter. - The ID of the pending safety check. + - `type: :image` - - `code: String` + The type of the output. Always `image`. - The type of the pending safety check. + - `:image` - - `message: String` + - `url: String` - Details about the pending safety check. + The URL of the image output from the code interpreter. - - `status: :in_progress | :completed | :incomplete` + - `status: :in_progress | :completed | :incomplete | 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 code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `:in_progress` @@ -98413,308 +109806,301 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :computer_call` + - `:interpreting` - The type of the computer call. Always `computer_call`. + - `:failed` - - `:computer_call` + - `type: :code_interpreter_call` - - `action: BetaComputerAction` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A click action. + - `:code_interpreter_call` - - `class Click` + - `agent: Agent{ agent_name}` - A click action. + The agent that produced this item. - - `button: :left | :right | :wheel | 2 more` + - `agent_name: String` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The canonical name of the agent that produced this item. - - `:left` + - `class LocalShellCall` - - `:right` + A tool call to run a command on the local shell. - - `:wheel` + - `id: String` - - `:back` + The unique ID of the local shell call. - - `:forward` + - `action: Action{ command, env, type, 3 more}` - - `type: :click` + Execute a shell command on the server. - Specifies the event type. For a click action, this property is always `click`. + - `command: Array[String]` - - `:click` + The command to run. - - `x: Integer` + - `env: Hash[Symbol, String]` - The x-coordinate where the click occurred. + Environment variables to set for the command. - - `y_: Integer` + - `type: :exec` - The y-coordinate where the click occurred. + The type of the local shell action. Always `exec`. - - `keys: Array[String]` + - `:exec` - The keys being held while clicking. + - `timeout_ms: Integer` - - `class DoubleClick` + Optional timeout in milliseconds for the command. - A double click action. + - `user: String` - - `keys: Array[String]` + Optional user to run the command as. - The keys being held while double-clicking. + - `working_directory: String` - - `type: :double_click` + Optional working directory to run the command in. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `call_id: String` - - `:double_click` + The unique ID of the local shell tool call generated by the model. - - `x: Integer` + - `status: :in_progress | :completed | :incomplete` - The x-coordinate where the double click occurred. + The status of the local shell call. - - `y_: Integer` + - `:in_progress` - The y-coordinate where the double click occurred. + - `:completed` - - `class Drag` + - `:incomplete` - A drag action. + - `type: :local_shell_call` - - `path: Array[Path{ x, y_}]` + The type of the local shell call. Always `local_shell_call`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `:local_shell_call` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `agent: Agent{ agent_name}` - - `x: Integer` + The agent that produced this item. - The x-coordinate. + - `agent_name: String` - - `y_: Integer` + The canonical name of the agent that produced this item. - The y-coordinate. + - `class LocalShellCallOutput` - - `type: :drag` + The output of a local shell tool call. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: String` - - `:drag` + The unique ID of the local shell tool call generated by the model. - - `keys: Array[String]` + - `output: String` - The keys being held while dragging the mouse. + A JSON string of the output of the local shell tool call. - - `class Keypress` + - `type: :local_shell_call_output` - A collection of keypresses the model would like to perform. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `keys: Array[String]` + - `:local_shell_call_output` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `agent: Agent{ 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. - - `class Move` + - `status: :in_progress | :completed | :incomplete` - A mouse move action. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `type: :move` + - `:in_progress` - Specifies the event type. For a move action, this property is always set to `move`. + - `:completed` - - `:move` + - `:incomplete` - - `x: Integer` + - `class BetaResponseFunctionShellToolCall` - The x-coordinate to move to. + A tool call that executes one or more shell commands in a managed environment. - - `y_: Integer` + - `id: String` - The y-coordinate to move to. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `keys: Array[String]` + - `action: Action{ commands, max_output_length, timeout_ms}` - The keys being held while moving the mouse. + The shell commands and limits that describe how to run the tool call. - - `class Screenshot` + - `commands: Array[String]` - A screenshot action. + - `max_output_length: Integer` - - `type: :screenshot` + Optional maximum number of characters to return from each command. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `timeout_ms: Integer` - - `:screenshot` + Optional timeout in milliseconds for the commands. - - `class Scroll` + - `call_id: String` - A scroll action. + The unique ID of the shell tool call generated by the model. - - `scroll_x: Integer` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - The horizontal scroll distance. + Represents the use of a local environment to perform shell actions. - - `scroll_y: Integer` + - `class BetaResponseLocalEnvironment` - The vertical scroll distance. + Represents the use of a local environment to perform shell actions. - - `type: :scroll` + - `type: :local` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The environment type. Always `local`. - - `:scroll` + - `:local` - - `x: Integer` + - `class BetaResponseContainerReference` - The x-coordinate where the scroll occurred. + Represents a container created with /v1/containers. - - `y_: Integer` + - `container_id: String` - The y-coordinate where the scroll occurred. + - `type: :container_reference` - - `keys: Array[String]` + The environment type. Always `container_reference`. - The keys being held while scrolling. + - `:container_reference` - - `class Type` + - `status: :in_progress | :completed | :incomplete` - An action to type in text. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `text: String` + - `:in_progress` - The text to type. + - `:completed` - - `type: :type` + - `:incomplete` - Specifies the event type. For a type action, this property is always set to `type`. + - `type: :shell_call` - - `:type` + The type of the item. Always `shell_call`. - - `class Wait` + - `:shell_call` - A wait action. + - `agent: Agent{ agent_name}` - - `type: :wait` + The agent that produced this item. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `agent_name: String` - - `:wait` + The canonical name of the agent that produced this item. - - `actions: BetaComputerActionList` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The execution context that produced this tool call. - - `class Click` + - `class Direct` - A click action. + - `type: :direct` - - `class DoubleClick` + - `:direct` - A double click action. + - `class Program` - - `class Drag` + - `caller_id: String` - A drag action. + The call ID of the program item that produced this tool call. - - `class Keypress` + - `type: :program` - A collection of keypresses the model would like to perform. + - `:program` - - `class Move` + - `created_by: String` - A mouse move action. + The ID of the entity that created this tool call. - - `class Screenshot` + - `class BetaResponseFunctionShellToolCallOutput` - A screenshot action. + The output of a shell tool call that was emitted. - - `class Scroll` + - `id: String` - A scroll action. + The unique ID of the shell call output. Populated when this item is returned via API. - - `class Type` + - `call_id: String` - An action to type in text. + The unique ID of the shell tool call generated by the model. - - `class Wait` + - `max_output_length: Integer` - A wait action. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `agent: Agent{ agent_name}` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - The agent that produced this item. + An array of shell call output contents - - `agent_name: String` + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The canonical name of the agent that produced this item. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `class ComputerCallOutput` + - `class Timeout` - The output of a computer tool call. + Indicates that the shell call exceeded its configured time limit. - - `call_id: String` + - `type: :timeout` - The ID of the computer tool call that produced the output. + The outcome type. Always `timeout`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `:timeout` - A computer screenshot image used with the computer use tool. + - `class Exit` - - `type: :computer_screenshot` + Indicates that the shell commands finished and returned an exit code. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `exit_code: Integer` - - `:computer_screenshot` + Exit code from the shell process. - - `file_id: String` + - `type: :exit` - The identifier of an uploaded file that contains the screenshot. + The outcome type. Always `exit`. - - `image_url: String` + - `:exit` - The URL of the screenshot image. + - `stderr: String` - - `type: :computer_call_output` + The standard error output that was captured. - The type of the computer tool call output. Always `computer_call_output`. + - `stdout: String` - - `:computer_call_output` + The standard output that was captured. - - `id: String` + - `created_by: String` - The ID of the computer tool call output. + The identifier of the actor that created the item. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `status: :in_progress | :completed | :incomplete` - The safety checks reported by the API that have been acknowledged by the developer. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `id: String` + - `:in_progress` - The ID of the pending safety check. + - `:completed` - - `code: String` + - `:incomplete` - The type of the pending safety check. + - `type: :shell_call_output` - - `message: String` + The type of the shell call output. Always `shell_call_output`. - Details about the pending safety check. + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -98724,111 +110110,109 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `caller_: Direct{ type} | Program{ 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` + - `class Direct` - - `:completed` + - `type: :direct` - - `:incomplete` + - `:direct` - - `class BetaResponseFunctionWebSearch` + - `class Program` - 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. + - `caller_id: String` - - `id: String` + The call ID of the program item that produced this tool call. - The unique ID of the web search tool call. + - `type: :program` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `: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). + - `created_by: String` - - `class Search` + The identifier of the actor that created the item. - Action type "search" - Performs a web search query. + - `class BetaResponseApplyPatchToolCall` - - `type: :search` + A tool call that applies file diffs by creating, deleting, or updating files. - The action type. + - `id: String` - - `:search` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `queries: Array[String]` + - `call_id: String` - The search queries. + The unique ID of the apply patch tool call generated by the model. - - `query: String` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The search query. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `sources: Array[Source{ type, url}]` + - `class CreateFile` - The sources used in the search. + Instruction describing how to create a file via the apply_patch tool. - - `type: :url` + - `diff: String` - The type of source. Always `url`. + Diff to apply. - - `:url` + - `path: String` - - `url: String` + Path of the file to create. - The URL of the source. + - `type: :create_file` - - `class OpenPage` + Create a new file with the provided diff. - Action type "open_page" - Opens a specific URL from search results. + - `:create_file` - - `type: :open_page` + - `class DeleteFile` - The action type. + Instruction describing how to delete a file via the apply_patch tool. - - `:open_page` + - `path: String` - - `url: String` + Path of the file to delete. - The URL opened by the model. + - `type: :delete_file` - - `class FindInPage` + Delete the specified file. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `:delete_file` - - `pattern: String` + - `class UpdateFile` - The pattern or text to search for within the page. + Instruction describing how to update a file via the apply_patch tool. - - `type: :find_in_page` + - `diff: String` - The action type. + Diff to apply. - - `:find_in_page` + - `path: String` - - `url: String` + Path of the file to update. - The URL of the page searched for the pattern. + - `type: :update_file` - - `status: :in_progress | :searching | :completed | :failed` + Update an existing file with the provided diff. - The status of the web search tool call. + - `:update_file` - - `:in_progress` + - `status: :in_progress | :completed` - - `:searching` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:completed` + - `:in_progress` - - `:failed` + - `:completed` - - `type: :web_search_call` + - `type: :apply_patch_call` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `apply_patch_call`. - - `:web_search_call` + - `:apply_patch_call` - `agent: Agent{ agent_name}` @@ -98838,32 +110222,55 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The execution context that produced this tool call. - - `arguments: String` + - `class Direct` - A JSON string of the arguments to pass to the function. + - `type: :direct` - - `call_id: String` + - `:direct` - The unique ID of the function tool call generated by the model. + - `class Program` - - `name: String` + - `caller_id: String` - The name of the function to run. + The call ID of the program item that produced this tool call. - - `type: :function_call` + - `type: :program` - The type of the function tool call. Always `function_call`. + - `:program` - - `:function_call` + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + The output emitted by an apply patch tool call. - `id: String` - The unique ID of the function tool call. + 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 | :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: Agent{ agent_name}` @@ -98893,160 +110300,150 @@ puts(beta_compacted_response) - `:program` - - `namespace: String` - - The namespace of the function to run. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` + - `created_by: String` - - `:incomplete` + The ID of the entity that created this tool call output. - - `class FunctionCallOutput` + - `output: String` - The output of a function tool call. + Optional textual output returned by the apply patch tool. - - `call_id: String` + - `class McpCall` - The unique ID of the function tool call generated by the model. + An invocation of a tool on an MCP server. - - `output: String | BetaResponseFunctionCallOutputItemList` + - `id: String` - Text, image, or file output of the function tool call. + The unique ID of the tool call. - - `String = String` + - `arguments: String` - A JSON string of the output of the function tool call. + A JSON string of the arguments passed to the tool. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `name: String` - An array of content outputs (text, image, file) for the function tool call. + The name of the tool that was run. - - `class BetaResponseInputTextContent` + - `server_label: String` - A text input to the model. + The label of the MCP server running the tool. - - `text: String` + - `type: :mcp_call` - The text input to the model. + The type of the item. Always `mcp_call`. - - `type: :input_text` + - `:mcp_call` - The type of the input item. Always `input_text`. + - `agent: Agent{ agent_name}` - - `:input_text` + The agent that produced this item. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` + - `approval_request_id: String` - The breakpoint mode. Always `explicit`. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `:explicit` + - `error: String` - - `class BetaResponseInputImageContent` + The error from the tool call, if any. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `output: String` - - `type: :input_image` + The output from the tool call. - The type of the input item. Always `input_image`. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `:input_image` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `detail: :low | :high | :auto | :original` + - `:in_progress` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:completed` - - `:low` + - `:incomplete` - - `:high` + - `:calling` - - `:auto` + - `:failed` - - `:original` + - `class McpListTools` - - `file_id: String` + A list of tools available on an MCP server. - The ID of the file to be sent to the model. + - `id: String` - - `image_url: String` + The unique ID of the list. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `server_label: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The label of the 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. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `mode: :explicit` + The tools available on the server. - The breakpoint mode. Always `explicit`. + - `input_schema: untyped` - - `:explicit` + The JSON schema describing the tool's input. - - `class BetaResponseInputFileContent` + - `name: String` - A file input to the model. + The name of the tool. - - `type: :input_file` + - `annotations: untyped` - The type of the input item. Always `input_file`. + Additional annotations about the tool. - - `:input_file` + - `description: String` - - `detail: :auto | :low | :high` + The description of 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_list_tools` - - `:auto` + The type of the item. Always `mcp_list_tools`. - - `:low` + - `:mcp_list_tools` - - `:high` + - `agent: Agent{ agent_name}` - - `file_data: String` + The agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `agent_name: String` - - `file_id: String` + The canonical name of the agent that produced this item. - The ID of the file to be sent to the model. + - `error: String` - - `file_url: String` + Error message if the server could not list tools. - The URL of the file to be sent to the model. + - `class McpApprovalRequest` - - `filename: String` + A request for human approval of a tool invocation. - The name of the file to be sent to the model. + - `id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The unique ID of the 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. + - `arguments: String` - - `mode: :explicit` + A JSON string of arguments for the tool. - The breakpoint mode. Always `explicit`. + - `name: String` - - `:explicit` + The name of the tool to run. - - `type: :function_call_output` + - `server_label: String` - The type of the function tool call output. Always `function_call_output`. + The label of the MCP server making the request. - - `:function_call_output` + - `type: :mcp_approval_request` - - `id: String` + The type of the item. Always `mcp_approval_request`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -99056,181 +110453,168 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class McpApprovalResponse` - The execution context that produced this tool call. + A response to an MCP approval request. - - `class Direct` + - `id: String` - - `type: :direct` + The unique ID of the approval response - The caller type. Always `direct`. + - `approval_request_id: String` - - `:direct` + The ID of the approval request being answered. - - `class Program` + - `approve: bool` - - `caller_id: String` + Whether the request was approved. - The call ID of the program item that produced this tool call. + - `type: :mcp_approval_response` - - `type: :program` + The type of the item. Always `mcp_approval_response`. - The caller type. Always `program`. + - `:mcp_approval_response` - - `:program` + - `agent: Agent{ agent_name}` - - `status: :in_progress | :completed | :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` + - `reason: String` - - `:incomplete` + Optional reason for the decision. - - `class AgentMessage` + - `class BetaResponseCustomToolCall` - A message routed between agents. + A call to a custom tool created by the model. - - `author: String` + - `call_id: String` - The sending agent identity. + An identifier used to map this custom tool call to a tool call output. - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + - `input: String` - Plaintext, image, or encrypted content sent between agents. + The input for the custom tool call generated by the model. - - `class BetaResponseInputTextContent` + - `name: String` - A text input to the model. + The name of the custom tool being called. - - `class BetaResponseInputImageContent` + - `type: :custom_tool_call` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the custom tool call. Always `custom_tool_call`. - - `class EncryptedContent` + - `:custom_tool_call` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `id: String` - - `encrypted_content: String` + The unique ID of the custom tool call in the OpenAI platform. - Opaque encrypted content. + - `agent: Agent{ agent_name}` - - `type: :encrypted_content` + The agent that produced this item. - The type of the input item. Always `encrypted_content`. + - `agent_name: String` - - `:encrypted_content` + The canonical name of the agent that produced this item. - - `recipient: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The destination agent identity. + The execution context that produced this tool call. - - `type: :agent_message` + - `class Direct` - The item type. Always `agent_message`. + - `type: :direct` - - `:agent_message` + - `:direct` - - `id: String` + - `class Program` - The unique ID of this agent message item. + - `caller_id: String` - - `agent: Agent{ 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. + - `namespace: String` - - `class MultiAgentCall` + The namespace of the custom tool being called. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `class BetaResponseCustomToolCallOutputItem` - The multi-agent action that was executed. + The output of a custom tool call from your code, being sent back to the model. - - `:spawn_agent` + - `id: String` - - `:interrupt_agent` + The unique ID of the custom tool call output item. - - `:list_agents` + - `status: :in_progress | :completed | :incomplete` - - `:send_message` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:followup_task` + - `:in_progress` - - `:wait_agent` + - `:completed` - - `arguments: String` + - `:incomplete` - The action arguments as a JSON string. + - `created_by: String` - - `call_id: String` + The identifier of the actor that created the item. - The unique ID linking this call to its output. + - `output_index: Integer` - - `type: :multi_agent_call` + The index of the output item that was marked done. - The item type. Always `multi_agent_call`. + - `sequence_number: Integer` - - `:multi_agent_call` + The sequence number of this event. - - `id: String` + - `type: :"response.output_item.done"` - The unique ID of this multi-agent call. + The type of the event. Always `response.output_item.done`. + + - `:"response.output_item.done"` - `agent: Agent{ 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. - - `class MultiAgentCallOutput` - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action that produced this result. - - - `:spawn_agent` - - - `:interrupt_agent` - - - `:list_agents` - - - `:send_message` - - - `:followup_task` - - - `:wait_agent` +### Beta Response Output Message - - `call_id: String` +- `class BetaResponseOutputMessage` - The unique ID of the multi-agent call. + An output message from the model. - - `output: Array[Output{ text, type, annotations}]` + - `id: String` - Text output returned by the multi-agent action. + The unique ID of the output message. - - `text: String` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The text content. + The content of the output message. - - `type: :output_text` + - `class BetaResponseOutputText` - The content type. Always `output_text`. + A text output from the model. - - `:output_text` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + The annotations of the text output. - Citations associated with the text content. + - `class FileCitation` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + A citation to a file. - `file_id: String` @@ -99246,47 +110630,51 @@ puts(beta_compacted_response) - `type: :file_citation` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `:file_citation` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `class URLCitation` + + A citation for a web resource used to generate a model response. - `end_index: Integer` - 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: Integer` - 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. - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `class ContainerFileCitation` + + 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: Integer` - 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` @@ -99294,71 +110682,82 @@ puts(beta_compacted_response) - `start_index: Integer` - 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` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. - - `:container_file_citation` + - `index: Integer` - - `type: :multi_agent_call_output` + The index of the file in the list of files. - The item type. Always `multi_agent_call_output`. + - `type: :file_path` - - `:multi_agent_call_output` + The type of the file path. Always `file_path`. - - `id: String` + - `:file_path` - The unique ID of this multi-agent call output. + - `text: String` - - `agent: Agent{ agent_name}` + The text output from the model. - The agent that produced this item. + - `type: :output_text` - - `agent_name: String` + The type of the output text. Always `output_text`. - The canonical name of the agent that produced this item. + - `:output_text` - - `class ToolSearchCall` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `arguments: untyped` + - `token: String` - The arguments supplied to the tool search call. + - `bytes: Array[Integer]` - - `type: :tool_search_call` + - `logprob: Float` - The item type. Always `tool_search_call`. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `:tool_search_call` + - `token: String` - - `id: String` + - `bytes: Array[Integer]` - The unique ID of this tool search call. + - `logprob: Float` - - `agent: Agent{ agent_name}` + - `class BetaResponseOutputRefusal` - 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. - - `call_id: String` + - `type: :refusal` - The unique ID of the tool search call generated by the model. + The type of the refusal. Always `refusal`. - - `execution: :server | :client` + - `:refusal` - Whether tool search was executed by the server or by the client. + - `role: :assistant` - - `:server` + The role of the output message. Always `assistant`. - - `:client` + - `:assistant` - `status: :in_progress | :completed | :incomplete` - The status of the tool search call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `:in_progress` @@ -99366,1262 +110765,1214 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseToolSearchOutputItemParam` - - - `tools: Array[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool` + - `type: :message` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of the output message. Always `message`. - - `name: String` + - `:message` - The name of the function to call. + - `agent: Agent{ agent_name}` - - `parameters: Hash[Symbol, untyped]` + The agent that produced this item. - A JSON schema object describing the parameters of the function. + - `agent_name: String` - - `strict: bool` + The canonical name of the agent that produced this item. - Whether strict parameter validation is enforced for this function tool. + - `phase: :commentary | :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. - The type of the function tool. Always `function`. + - `:commentary` - - `:function` + - `:final_answer` - - `allowed_callers: Array[:direct | :programmatic]` +### Beta Response Output Refusal - The tool invocation context(s). +- `class BetaResponseOutputRefusal` - - `:direct` + A refusal from the model. - - `:programmatic` + - `refusal: String` - - `defer_loading: bool` + The refusal explanation from the model. - Whether this function is deferred and loaded via tool search. + - `type: :refusal` - - `description: String` + The type of the refusal. Always `refusal`. - A description of the function. Used by the model to determine whether or not to call the function. + - `:refusal` - - `output_schema: Hash[Symbol, untyped]` +### Beta Response Output Text - A JSON schema object describing the JSON value encoded in string outputs for this function. +- `class BetaResponseOutputText` - - `class BetaFileSearchTool` + A text output from 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). + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `type: :file_search` + The annotations of the text output. - The type of the file search tool. Always `file_search`. + - `class FileCitation` - - `:file_search` + A citation to a file. - - `vector_store_ids: Array[String]` + - `file_id: String` - The IDs of the vector stores to search. + The ID of the file. - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `filename: String` - A filter to apply. + The filename of the file cited. - - `class ComparisonFilter` + - `index: Integer` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the file in the list of files. - - `key: String` + - `type: :file_citation` - The key to compare against the value. + The type of the file citation. Always `file_citation`. - - `type: :eq | :ne | :gt | 5 more` + - `:file_citation` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class URLCitation` - - `eq`: equals - - `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 citation for a web resource used to generate a model response. - - `:eq` + - `end_index: Integer` - - `:ne` + The index of the last character of the URL citation in the message. - - `:gt` + - `start_index: Integer` - - `:gte` + The index of the first character of the URL citation in the message. - - `:lt` + - `title: String` - - `:lte` + The title of the web resource. - - `:in` + - `type: :url_citation` - - `:nin` + The type of the URL citation. Always `url_citation`. - - `value: String | Float | bool | Array[untyped]` + - `:url_citation` - The value to compare against the attribute key; supports string, number, or boolean types. + - `url: String` - - `String = String` + The URL of the web resource. - - `Float = Float` + - `class ContainerFileCitation` - - `UnionMember2 = bool` + A citation for a container file used to generate a model response. - - `UnionMember3 = Array[untyped]` + - `container_id: String` - - `class CompoundFilter` + The ID of the container file. - Combine multiple filters using `and` or `or`. + - `end_index: Integer` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The index of the last character of the container file citation in the message. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `file_id: String` - - `class ComparisonFilter` + The ID of the file. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `filename: String` - - `key: String` + The filename of the container file cited. - The key to compare against the value. + - `start_index: Integer` - - `type: :eq | :ne | :gt | 5 more` + The index of the first character of the container file citation in the message. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: :container_file_citation` - - `eq`: equals - - `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 container file citation. Always `container_file_citation`. - - `:eq` + - `:container_file_citation` - - `:ne` + - `class FilePath` - - `:gt` + A path to a file. - - `:gte` + - `file_id: String` - - `:lt` + The ID of the file. - - `:lte` + - `index: Integer` - - `:in` + The index of the file in the list of files. - - `:nin` + - `type: :file_path` - - `value: String | Float | bool | Array[untyped]` + The type of the file path. Always `file_path`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `:file_path` - - `String = String` + - `text: String` - - `Float = Float` + The text output from the model. - - `UnionMember2 = bool` + - `type: :output_text` - - `UnionMember3 = Array[untyped]` + The type of the output text. Always `output_text`. - - `UnionMember1 = untyped` + - `:output_text` - - `type: :and | :or` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - Type of operation: `and` or `or`. + - `token: String` - - `:and` + - `bytes: Array[Integer]` - - `:or` + - `logprob: Float` - - `max_num_results: Integer` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `token: String` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `bytes: Array[Integer]` - Ranking options for search. + - `logprob: Float` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` +### Beta Response Output Text Annotation Added Event - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +- `class BetaResponseOutputTextAnnotationAddedEvent` - - `embedding_weight: Float` + Emitted when an annotation is added to output text content. - The weight of the embedding in the reciprocal ranking fusion. + - `annotation: untyped` - - `text_weight: Float` + The annotation object being added. (See annotation schema for details.) - The weight of the text in the reciprocal ranking fusion. + - `annotation_index: Integer` - - `ranker: :auto | :"default-2024-11-15"` + The index of the annotation within the content part. - The ranker to use for the file search. + - `content_index: Integer` - - `:auto` + The index of the content part within the output item. - - `:"default-2024-11-15"` + - `item_id: String` - - `score_threshold: Float` + The unique identifier of the item to which the annotation is being added. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `output_index: Integer` - - `class BetaComputerTool` + The index of the output item in the response's output array. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `sequence_number: Integer` - - `type: :computer` + The sequence number of this event. - The type of the computer tool. Always `computer`. + - `type: :"response.output_text.annotation.added"` - - `:computer` + The type of the event. Always 'response.output_text.annotation.added'. - - `class BetaComputerUsePreviewTool` + - `:"response.output_text.annotation.added"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: Agent{ agent_name}` - - `display_height: Integer` + The agent that owns this multi-agent streaming event. - The height of the computer display. + - `agent_name: String` - - `display_width: Integer` + The canonical name of the agent that produced this item. - The width of the computer display. +### Beta Response Prompt - - `environment: :windows | :mac | :linux | 2 more` +- `class BetaResponsePrompt` - The type of computer environment to control. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `:windows` + - `id: String` - - `:mac` + The unique identifier of the prompt template to use. - - `:linux` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:ubuntu` + 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. - - `:browser` + - `String = String` - - `type: :computer_use_preview` + - `class BetaResponseInputText` - The type of the computer use tool. Always `computer_use_preview`. + A text input to the model. - - `:computer_use_preview` + - `text: String` - - `class BetaWebSearchTool` + The text input to the model. - 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: :input_text` - - `type: :web_search | :web_search_2025_08_26` + The type of the input item. Always `input_text`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `:input_text` - - `:web_search` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: Filters{ allowed_domains}` + - `mode: :explicit` - Filters for the search. + The breakpoint mode. Always `explicit`. - - `allowed_domains: Array[String]` + - `:explicit` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `class BetaResponseInputImage` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `search_context_size: :low | :medium | :high` + - `detail: :low | :high | :auto | :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: UserLocation{ city, country, region, 2 more}` + - `:auto` - The approximate location of the user. + - `:original` - - `city: 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: 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: String` - - `region: 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: String` - - `timezone: 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: PromptCacheBreakpoint{ mode}` - - `type: :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`. - - `class Mcp` + - `: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). + - `class BetaResponseInputFile` - - `server_label: String` + A file input to the model. - A label for this MCP server, used to identify it in tool calls. + - `type: :input_file` - - `type: :mcp` + The type of the input item. Always `input_file`. - The type of the MCP tool. Always `mcp`. + - `:input_file` - - `:mcp` + - `detail: :auto | :low | :high` - - `allowed_callers: Array[:direct | :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`. - The tool invocation context(s). + - `:auto` - - `:direct` + - `:low` - - `:programmatic` + - `:high` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `file_data: String` - List of allowed tool names or a filter object. + The content of the file to be sent to the model. - - `McpAllowedTools = Array[String]` + - `file_id: String` - A string array of allowed tool names + The ID of the file to be sent to the model. - - `class McpToolFilter` + - `file_url: String` - A filter object to specify which tools are allowed. + The URL of the file to be sent to the model. - - `read_only: bool` + - `filename: String` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The name of the file to be sent to the model. - - `tool_names: Array[String]` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - List of allowed tool names. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `authorization: String` + - `mode: :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. + The breakpoint mode. Always `explicit`. - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:explicit` - 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). + - `version: String` - Currently supported `connector_id` values are: + Optional version of the prompt template. - - 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` +### Beta Response Queued Event - - `:connector_dropbox` +- `class BetaResponseQueuedEvent` - - `:connector_gmail` + Emitted when a response is queued and waiting to be processed. - - `:connector_googlecalendar` + - `response: BetaResponse` - - `:connector_googledrive` + The full response object that is queued. - - `:connector_microsoftteams` + - `id: String` - - `:connector_outlookcalendar` + Unique identifier for this Response. - - `:connector_outlookemail` + - `created_at: Float` - - `:connector_sharepoint` + Unix timestamp (in seconds) of when this Response was created. - - `defer_loading: bool` + - `error: BetaResponseError` - Whether this MCP tool is deferred and discovered via tool search. + An error object returned when the model fails to generate a Response. - - `headers: Hash[Symbol, String]` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The error code for the response. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:server_error` - Specify which of the MCP server's tools require approval. + - `:rate_limit_exceeded` - - `class McpToolApprovalFilter` + - `:invalid_prompt` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `:bio_policy` - - `always: Always{ read_only, tool_names}` + - `:vector_store_timeout` - A filter object to specify which tools are allowed. + - `:invalid_image` - - `read_only: bool` + - `:invalid_image_format` - Indicates whether or not a tool modifies data or is read-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_base64_image` - - `tool_names: Array[String]` + - `:invalid_image_url` - List of allowed tool names. + - `:image_too_large` - - `never: Never{ read_only, tool_names}` + - `:image_too_small` - A filter object to specify which tools are allowed. + - `:image_parse_error` - - `read_only: bool` + - `:image_content_policy_violation` - Indicates whether or not a tool modifies data or is read-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_mode` - - `tool_names: Array[String]` + - `:image_file_too_large` - List of allowed tool names. + - `:unsupported_image_media_type` - - `McpToolApprovalSetting = :always | :never` + - `:empty_image_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. + - `:failed_to_download_image` - - `:always` + - `:image_file_not_found` - - `:never` + - `message: String` - - `server_description: String` + A human-readable description of the error. - Optional description of the MCP server, used to provide more context. + - `incomplete_details: IncompleteDetails{ reason}` - - `server_url: String` + Details about why the response is incomplete. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `reason: :max_output_tokens | :content_filter` - - `tunnel_id: String` + The reason why the response is 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. + - `:max_output_tokens` - - `class CodeInterpreter` + - `:content_filter` - A tool that runs Python code to help generate a response to a prompt. + - `instructions: String | Array[BetaResponseInputItem]` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + A system (or developer) message inserted into the model's context. - 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. + 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 = String` - The container ID. - - - `class CodeInterpreterToolAuto` - - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - - `type: :auto` - - Always `auto`. + A text input to the model, equivalent to a text input with the + `developer` role. - - `:auto` + - `InputItemList = Array[BetaResponseInputItem]` - - `file_ids: Array[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. + - `class BetaEasyInputMessage` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"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 | BetaResponseInputMessageContentList` - - `:"1g"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `:"4g"` + - `String = String` - - `:"16g"` + A text input to the model. - - `:"64g"` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + A list of one or many input items to the model, containing different content + types. - Network access policy for the container. + - `class BetaResponseInputText` - - `class BetaContainerNetworkPolicyDisabled` + A text input to the model. - - `type: :disabled` + - `text: String` - Disable outbound network access. Always `disabled`. + The text input to the model. - - `:disabled` + - `type: :input_text` - - `class BetaContainerNetworkPolicyAllowlist` + The type of the input item. Always `input_text`. - - `allowed_domains: Array[String]` + - `:input_text` - A list of allowed domains when type is `allowlist`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `type: :allowlist` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Allow outbound network access only to specified domains. Always `allowlist`. + - `mode: :explicit` - - `:allowlist` + The breakpoint mode. Always `explicit`. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `:explicit` - Optional domain-scoped secrets for allowlisted domains. + - `class BetaResponseInputImage` - - `domain: String` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The domain associated with the secret. + - `detail: :low | :high | :auto | :original` - - `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 name of the secret to inject for the domain. + - `:low` - - `value: String` + - `:high` - The secret value to inject for the domain. + - `:auto` - - `type: :code_interpreter` + - `:original` - The type of the code interpreter tool. Always `code_interpreter`. + - `type: :input_image` - - `:code_interpreter` + The type of the input item. Always `input_image`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:input_image` - The tool invocation context(s). + - `file_id: String` - - `:direct` + The ID of the file to be sent to the model. - - `:programmatic` + - `image_url: String` - - `class ProgrammaticToolCalling` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: :programmatic_tool_calling` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The type of the tool. Always `programmatic_tool_calling`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:programmatic_tool_calling` + - `mode: :explicit` - - `class ImageGeneration` + The breakpoint mode. Always `explicit`. - A tool that generates images using the GPT image models. + - `:explicit` - - `type: :image_generation` + - `class BetaResponseInputFile` - The type of the image generation tool. Always `image_generation`. + A file input to the model. - - `:image_generation` + - `type: :input_file` - - `action: :generate | :edit | :auto` + The type of the input item. Always `input_file`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `:input_file` - - `:generate` + - `detail: :auto | :low | :high` - - `:edit` + 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` - - `background: :transparent | :opaque | :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` + - `:low` - - `input_fidelity: :high | :low` + - `: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`. + - `file_data: String` - - `:high` + The content of the file to be sent to the model. - - `:low` + - `file_id: String` - - `input_image_mask: InputImageMask{ file_id, image_url}` + The ID of the file to be sent to the model. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `file_url: String` - - `file_id: String` + The URL of the file to be sent to the model. - File ID for the mask image. + - `filename: String` - - `image_url: String` + The name of the file to be sent to the model. - Base64-encoded mask image. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 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. - The image generation model to use. Default: `gpt-image-1`. + - `mode: :explicit` - - `String = String` + The breakpoint mode. Always `explicit`. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `:explicit` - The image generation model to use. Default: `gpt-image-1`. + - `role: :user | :assistant | :system | :developer` - - `:"gpt-image-1"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `:"gpt-image-1-mini"` + - `:user` - - `:"gpt-image-2"` + - `:assistant` - - `:"gpt-image-2-2026-04-21"` + - `:system` - - `:"gpt-image-1.5"` + - `:developer` - - `:"chatgpt-image-latest"` + - `phase: :commentary | :final_answer` - - `moderation: :auto | :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. - Moderation level for the generated image. Default: `auto`. + - `:commentary` - - `:auto` + - `:final_answer` - - `:low` + - `type: :message` - - `output_compression: Integer` + The type of the message input. Always `message`. - Compression level for the output image. Default: 100. + - `:message` - - `output_format: :png | :webp | :jpeg` + - `class Message` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + 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. - - `:png` + - `content: BetaResponseInputMessageContentList` - - `:webp` + A list of one or many input items to the model, containing different content + types. - - `:jpeg` + - `role: :user | :system | :developer` - - `partial_images: Integer` + The role of the message input. One of `user`, `system`, or `developer`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `:user` - - `quality: :low | :medium | :high | :auto` + - `:system` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `:developer` - - `:low` + - `agent: Agent{ 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: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `status: :in_progress | :completed | :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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `String = String` + - `:in_progress` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `:completed` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `:incomplete` - - `:"1024x1024"` + - `type: :message` - - `:"1024x1536"` + The type of the message input. Always set to `message`. - - `:"1536x1024"` + - `:message` - - `:auto` + - `class BetaResponseOutputMessage` - - `class LocalShell` + An output message from the model. - A tool that allows the model to execute shell commands in a local environment. + - `id: String` - - `type: :local_shell` + The unique ID of the output message. - The type of the local shell tool. Always `local_shell`. + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - - `:local_shell` + The content of the output message. - - `class BetaFunctionShellTool` + - `class BetaResponseOutputText` - A tool that allows the model to execute shell commands. + A text output from the model. - - `type: :shell` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - The type of the shell tool. Always `shell`. + The annotations of the text output. - - `:shell` + - `class FileCitation` - - `allowed_callers: Array[:direct | :programmatic]` + A citation to a file. - The tool invocation context(s). + - `file_id: String` - - `:direct` + The ID of the file. - - `:programmatic` + - `filename: String` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + The filename of the file cited. - - `class BetaContainerAuto` + - `index: Integer` - - `type: :container_auto` + The index of the file in the list of files. - Automatically creates a container for this request + - `type: :file_citation` - - `:container_auto` + The type of the file citation. Always `file_citation`. - - `file_ids: Array[String]` + - `:file_citation` - An optional list of uploaded files to make available to your code. + - `class URLCitation` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + A citation for a web resource used to generate a model response. - The memory limit for the container. + - `end_index: Integer` - - `:"1g"` + The index of the last character of the URL citation in the message. - - `:"4g"` + - `start_index: Integer` - - `:"16g"` + The index of the first character of the URL citation in the message. - - `:"64g"` + - `title: String` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + The title of the web resource. - Network access policy for the container. + - `type: :url_citation` - - `class BetaContainerNetworkPolicyDisabled` + The type of the URL citation. Always `url_citation`. - - `class BetaContainerNetworkPolicyAllowlist` + - `:url_citation` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `url: String` - An optional list of skills referenced by id or inline data. + The URL of the web resource. - - `class BetaSkillReference` + - `class ContainerFileCitation` - - `skill_id: String` + A citation for a container file used to generate a model response. - The ID of the referenced skill. + - `container_id: String` - - `type: :skill_reference` + The ID of the container file. - References a skill created with the /v1/skills endpoint. + - `end_index: Integer` - - `:skill_reference` + The index of the last character of the container file citation in the message. - - `version: String` + - `file_id: String` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The ID of the file. - - `class BetaInlineSkill` + - `filename: String` - - `description: String` + The filename of the container file cited. - The description of the skill. + - `start_index: Integer` - - `name: String` + The index of the first character of the container file citation in the message. - The name of the skill. + - `type: :container_file_citation` - - `source: BetaInlineSkillSource` + The type of the container file citation. Always `container_file_citation`. - Inline skill payload + - `:container_file_citation` - - `data: String` + - `class FilePath` - Base64-encoded skill zip bundle. + A path to a file. - - `media_type: :"application/zip"` + - `file_id: String` - The media type of the inline skill payload. Must be `application/zip`. + The ID of the file. - - `:"application/zip"` + - `index: Integer` - - `type: :base64` + The index of the file in the list of files. - The type of the inline skill source. Must be `base64`. + - `type: :file_path` - - `:base64` + The type of the file path. Always `file_path`. - - `type: :inline` + - `:file_path` - Defines an inline skill for this request. + - `text: String` - - `:inline` + The text output from the model. - - `class BetaLocalEnvironment` + - `type: :output_text` - - `type: :local` + The type of the output text. Always `output_text`. - Use a local computer environment. + - `:output_text` - - `:local` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `skills: Array[BetaLocalSkill]` + - `token: String` - An optional list of skills. + - `bytes: Array[Integer]` - - `description: String` + - `logprob: Float` - The description of the skill. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `name: String` + - `token: String` - The name of the skill. + - `bytes: Array[Integer]` - - `path: String` + - `logprob: Float` - The path to the directory containing the skill. + - `class BetaResponseOutputRefusal` - - `class BetaContainerReference` + A refusal from the model. - - `container_id: String` + - `refusal: String` - The ID of the referenced container. + The refusal explanation from the model. - - `type: :container_reference` + - `type: :refusal` - References a container created with the /v1/containers endpoint + The type of the refusal. Always `refusal`. - - `:container_reference` + - `:refusal` - - `class BetaCustomTool` + - `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 | :completed | :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: Array[:direct | :programmatic]` + - `:incomplete` - The tool invocation context(s). + - `type: :message` - - `:direct` + The type of the output message. Always `message`. - - `:programmatic` + - `:message` - - `defer_loading: bool` + - `agent: Agent{ agent_name}` - Whether this tool should be deferred and discovered via tool search. + The agent that produced this item. - - `description: 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_: Text{ type} | Grammar{ definition, syntax, type}` + - `phase: :commentary | :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. - - `class Text` + - `:commentary` - Unconstrained free-form text. + - `:final_answer` - - `type: :text` + - `class BetaResponseFileSearchToolCall` - Unconstrained text format. Always `text`. + 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. - - `:text` + - `id: String` - - `class Grammar` + The unique ID of the file search tool call. - A grammar defined by the user. + - `queries: Array[String]` - - `definition: String` + The queries used to search for files. - The grammar definition. + - `status: :in_progress | :searching | :completed | 2 more` - - `syntax: :lark | :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` - - `class BetaNamespaceTool` + 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: Agent{ 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[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - The function/custom tools available inside this namespace. + The results of the file search tool call. - - `class Function` + - `attributes: Hash[Symbol, String | Float | bool]` - - `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 = String` - - `:function` + - `Float = Float` - - `allowed_callers: Array[:direct | :programmatic]` + - `UnionMember2 = bool` - The tool invocation context(s). + - `file_id: String` - - `:direct` + The unique ID of the file. - - `:programmatic` + - `filename: String` - - `defer_loading: bool` + The name of the file. - Whether this function should be deferred and discovered via tool search. + - `score: Float` - - `description: String` + The relevance score of the file - a value between 0 and 1. - - `output_schema: Hash[Symbol, untyped]` + - `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 that was retrieved from the file. - - `parameters: untyped` + - `class BetaResponseComputerToolCall` - - `strict: bool` + 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 to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `id: String` - - `class BetaCustomTool` + The unique ID of the computer 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) + - `call_id: String` - - `type: :namespace` + An identifier used when responding to the tool call with output. - The type of the tool. Always `namespace`. + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `:namespace` + The pending safety checks for the computer call. - - `class BetaToolSearchTool` + - `id: String` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the pending safety check. - - `type: :tool_search` + - `code: String` - The type of the tool. Always `tool_search`. + The type of the pending safety check. - - `:tool_search` + - `message: String` - - `description: String` + Details about the pending safety check. - Description shown to the model for a client-executed tool search tool. + - `status: :in_progress | :completed | :incomplete` - - `execution: :server | :client` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether tool search is executed by the server or by the client. + - `:in_progress` - - `:server` + - `:completed` - - `:client` + - `:incomplete` - - `parameters: untyped` + - `type: :computer_call` - Parameter schema for a client-executed tool search tool. + The type of the computer call. Always `computer_call`. - - `class BetaWebSearchPreviewTool` + - `:computer_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). + - `action: BetaComputerAction` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + A click action. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class Click` - - `:web_search_preview` + A click action. - - `:web_search_preview_2025_03_11` + - `button: :left | :right | :wheel | 2 more` - - `search_content_types: Array[:text | :image]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `:text` + - `:left` - - `:image` + - `:right` - - `search_context_size: :low | :medium | :high` + - `:wheel` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `:back` - - `:low` + - `:forward` - - `:medium` + - `type: :click` - - `:high` + Specifies the event type. For a click action, this property is always `click`. - - `user_location: UserLocation{ type, city, country, 2 more}` + - `:click` - The user's location. + - `x: Integer` - - `type: :approximate` + The x-coordinate where the click occurred. - The type of location approximation. Always `approximate`. + - `y_: Integer` - - `:approximate` + The y-coordinate where the click occurred. - - `city: String` + - `keys: Array[String]` - Free text input for the city of the user, e.g. `San Francisco`. + The keys being held while clicking. - - `country: String` + - `class DoubleClick` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A double click action. - - `region: String` + - `keys: Array[String]` - Free text input for the region of the user, e.g. `California`. + The keys being held while double-clicking. - - `timezone: String` + - `type: :double_click` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `class BetaApplyPatchTool` + - `:double_click` - Allows the assistant to create, delete, or update files using unified diffs. + - `x: Integer` - - `type: :apply_patch` + The x-coordinate where the double click occurred. - The type of the tool. Always `apply_patch`. + - `y_: Integer` - - `:apply_patch` + The y-coordinate where the double click occurred. - - `allowed_callers: Array[:direct | :programmatic]` + - `class Drag` - The tool invocation context(s). + A drag action. - - `:direct` + - `path: Array[Path{ x, y_}]` - - `:programmatic` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `type: :tool_search_output` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The item type. Always `tool_search_output`. + - `x: Integer` - - `:tool_search_output` + The x-coordinate. - - `id: String` + - `y_: Integer` - The unique ID of this tool search output. + The y-coordinate. - - `agent: Agent{ agent_name}` + - `type: :drag` - The agent that produced this item. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `agent_name: String` + - `:drag` - The canonical name of the agent that produced this item. + - `keys: Array[String]` - - `call_id: String` + The keys being held while dragging the mouse. - The unique ID of the tool search call generated by the model. + - `class Keypress` - - `execution: :server | :client` + A collection of keypresses the model would like to perform. - Whether tool search was executed by the server or by the client. + - `keys: Array[String]` - - `:server` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `:client` + - `type: :keypress` - - `status: :in_progress | :completed | :incomplete` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The status of the tool search output. + - `:keypress` - - `:in_progress` + - `class Move` - - `:completed` + A mouse move action. - - `:incomplete` + - `type: :move` - - `class AdditionalTools` + Specifies the event type. For a move action, this property is always set to `move`. - - `role: :developer` + - `:move` - The role that provided the additional tools. Only `developer` is supported. + - `x: Integer` - - `:developer` + The x-coordinate to move to. - - `tools: Array[BetaTool]` + - `y_: Integer` - A list of additional tools made available at this item. + The y-coordinate to move to. - - `class BetaFunctionTool` + - `keys: Array[String]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The keys being held while moving the mouse. - - `class BetaFileSearchTool` + - `class Screenshot` - 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. - - `class BetaComputerTool` + - `type: :screenshot` - 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 screenshot action, this property is always set to `screenshot`. - - `class BetaComputerUsePreviewTool` + - `:screenshot` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Scroll` - - `class BetaWebSearchTool` + A scroll action. - 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). + - `scroll_x: Integer` - - `class Mcp` + 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: Integer` - - `class CodeInterpreter` + The vertical scroll distance. - A tool that runs Python code to help generate a response to a prompt. + - `type: :scroll` - - `class ProgrammaticToolCalling` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class ImageGeneration` + - `:scroll` - A tool that generates images using the GPT image models. + - `x: Integer` - - `class LocalShell` + The x-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands in a local environment. + - `y_: Integer` - - `class BetaFunctionShellTool` + The y-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands. + - `keys: Array[String]` - - `class BetaCustomTool` + The keys being held while scrolling. - 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) + - `class Type` - - `class BetaNamespaceTool` + An action to type in text. - Groups function/custom tools under a shared namespace. + - `text: String` - - `class BetaToolSearchTool` + The text to type. - Hosted or BYOT tool search configuration for deferred tools. + - `type: :type` - - `class BetaWebSearchPreviewTool` + Specifies the event type. For a type action, this property is always set to `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). + - `:type` - - `class BetaApplyPatchTool` + - `class Wait` - Allows the assistant to create, delete, or update files using unified diffs. + A wait action. - - `type: :additional_tools` + - `type: :wait` - The item type. Always `additional_tools`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `:additional_tools` + - `:wait` - - `id: String` + - `actions: BetaComputerActionList` - The unique ID of this additional tools item. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `agent: Agent{ agent_name}` + - `class Click` - The agent that produced this item. + A click action. - - `agent_name: String` + - `class DoubleClick` - The canonical name of the agent that produced this item. + A double click action. - - `class BetaResponseReasoningItem` + - `class Drag` - 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 drag action. - - `id: String` + - `class Keypress` - The unique identifier of the reasoning content. + A collection of keypresses the model would like to perform. - - `summary: Array[Summary{ text, type}]` + - `class Move` - Reasoning summary content. + A mouse move action. - - `text: String` + - `class Screenshot` - A summary of the reasoning output from the model so far. + A screenshot action. - - `type: :summary_text` + - `class Scroll` - The type of the object. Always `summary_text`. + A scroll action. - - `:summary_text` + - `class Type` - - `type: :reasoning` + An action to type in text. - The type of the object. Always `reasoning`. + - `class Wait` - - `:reasoning` + A wait action. - `agent: Agent{ agent_name}` @@ -100631,53 +111982,58 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `content: Array[Content{ text, type}]` - - Reasoning text content. + - `class ComputerCallOutput` - - `text: String` + The output of a computer tool call. - The reasoning text from the model. + - `call_id: String` - - `type: :reasoning_text` + The ID of the computer tool call that produced the output. - The type of the reasoning text. Always `reasoning_text`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `:reasoning_text` + A computer screenshot image used with the computer use tool. - - `encrypted_content: String` + - `type: :computer_screenshot` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `status: :in_progress | :completed | :incomplete` + - `:computer_screenshot` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_id: String` - - `:in_progress` + The identifier of an uploaded file that contains the screenshot. - - `:completed` + - `image_url: String` - - `:incomplete` + The URL of the screenshot image. - - `class BetaResponseCompactionItemParam` + - `type: :computer_call_output` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The type of the computer tool call output. Always `computer_call_output`. - - `encrypted_content: String` + - `:computer_call_output` - The encrypted content of the compaction summary. + - `id: String` - - `type: :compaction` + The ID of the computer tool call output. - The type of the item. Always `compaction`. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:compaction` + The safety checks reported by the API that have been acknowledged by the developer. - `id: String` - The ID of the compaction item. + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. - `agent: Agent{ agent_name}` @@ -100687,112 +112043,111 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ImageGenerationCall` + - `status: :in_progress | :completed | :incomplete` - An image generation request made by the model. + 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 image generation call. + - `:completed` - - `result: String` + - `:incomplete` - The generated image encoded in base64. + - `class BetaResponseFunctionWebSearch` - - `status: :in_progress | :completed | :generating | :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. - The status of the image generation call. + - `id: String` - - `:in_progress` + The unique ID of the web search tool call. - - `:completed` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `:generating` + 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). - - `:failed` + - `class Search` - - `type: :image_generation_call` + Action type "search" - Performs a web search query. - The type of the image generation call. Always `image_generation_call`. + - `type: :search` - - `:image_generation_call` + The action type. - - `agent: Agent{ agent_name}` + - `:search` - The agent that produced this item. + - `queries: Array[String]` - - `agent_name: String` + The search queries. - The canonical name of the agent that produced this item. + - `query: String` - - `class BetaResponseCodeInterpreterToolCall` + The search query. - A tool call to run code. + - `sources: Array[Source{ type, url}]` - - `id: String` + The sources used in the search. - The unique ID of the code interpreter tool call. + - `type: :url` - - `code: String` + The type of source. Always `url`. - The code to run, or null if not available. + - `:url` - - `container_id: String` + - `url: String` - The ID of the container used to run the code. + The URL of the source. - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `class OpenPage` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Action type "open_page" - Opens a specific URL from search results. - - `class Logs` + - `type: :open_page` - The logs output from the code interpreter. + The action type. - - `logs: String` + - `:open_page` - The logs output from the code interpreter. + - `url: String` - - `type: :logs` + The URL opened by the model. - The type of the output. Always `logs`. + - `class FindInPage` - - `:logs` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `class Image` + - `pattern: String` - The image output from the code interpreter. + The pattern or text to search for within the page. - - `type: :image` + - `type: :find_in_page` - The type of the output. Always `image`. + The action type. - - `:image` + - `:find_in_page` - `url: String` - The URL of the image output from the code interpreter. + The URL of the page searched for the pattern. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `status: :in_progress | :searching | :completed | :failed` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the web search tool call. - `:in_progress` - - `:completed` - - - `:incomplete` + - `:searching` - - `:interpreting` + - `:completed` - `:failed` - - `type: :code_interpreter_call` + - `type: :web_search_call` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the web search tool call. Always `web_search_call`. - - `:code_interpreter_call` + - `:web_search_call` - `agent: Agent{ agent_name}` @@ -100802,63 +112157,32 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCall` - - A tool call to run a command on the local shell. - - - `id: String` - - The unique ID of the local shell call. - - - `action: Action{ command, env, type, 3 more}` - - Execute a shell command on the server. - - - `command: Array[String]` - - The command to run. - - - `env: Hash[Symbol, String]` - - Environment variables to set for the command. - - - `type: :exec` - - The type of the local shell action. Always `exec`. - - - `:exec` - - - `timeout_ms: Integer` - - Optional timeout in milliseconds for the command. - - - `user: String` + - `class BetaResponseFunctionToolCall` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: String` + - `arguments: String` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: String` - The unique ID of the local shell tool call generated by the model. - - - `status: :in_progress | :completed | :incomplete` + The unique ID of the function tool call generated by the model. - The status of the local shell 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`. - - `type: :local_shell_call` + - `:function_call` - The type of the local shell call. Always `local_shell_call`. + - `id: String` - - `:local_shell_call` + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -100868,35 +112192,34 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput` - - The output of a local shell tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class Direct` - - `output: String` + - `type: :direct` - A JSON string of the output of the local shell tool call. + - `:direct` - - `type: :local_shell_call_output` + - `class Program` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: String` - - `:local_shell_call_output` + The call ID of the program item that produced this tool call. - - `agent: Agent{ agent_name}` + - `type: :program` - The agent that produced this item. + - `:program` - - `agent_name: String` + - `namespace: String` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -100904,147 +112227,145 @@ puts(beta_compacted_response) - `:incomplete` - - `class ShellCall` - - A tool representing a request to execute one or more shell commands. + - `class FunctionCallOutput` - - `action: Action{ commands, max_output_length, timeout_ms}` + The output of a function tool call. - The shell commands and limits that describe how to run the tool call. + - `call_id: String` - - `commands: Array[String]` + The unique ID of the function tool call generated by the model. - Ordered shell commands for the execution environment to run. + - `output: String | BetaResponseFunctionCallOutputItemList` - - `max_output_length: Integer` + Text, image, or file output of the function tool call. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `String = String` - - `timeout_ms: Integer` + A JSON string of the output of the function tool call. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `call_id: String` + An array of content outputs (text, image, file) for the function tool call. - The unique ID of the shell tool call generated by the model. + - `class BetaResponseInputTextContent` - - `type: :shell_call` + A text input to the model. - The type of the item. Always `shell_call`. + - `text: String` - - `:shell_call` + The text input to the model. - - `id: String` + - `type: :input_text` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the input item. Always `input_text`. - - `agent: Agent{ agent_name}` + - `:input_text` - The agent that produced this item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `agent_name: String` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: :explicit` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `:explicit` - - `class Direct` + - `class BetaResponseInputImageContent` - - `type: :direct` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The caller type. Always `direct`. + - `type: :input_image` - - `:direct` + The type of the input item. Always `input_image`. - - `class Program` + - `:input_image` - - `caller_id: String` + - `detail: :low | :high | :auto | :original` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :program` + - `:low` - The caller type. Always `program`. + - `:high` - - `:program` + - `:auto` - - `environment: BetaLocalEnvironment | BetaContainerReference` + - `:original` - The environment to execute the shell commands in. + - `file_id: String` - - `class BetaLocalEnvironment` + The ID of the file to be sent to the model. - - `class BetaContainerReference` + - `image_url: String` - - `status: :in_progress | :completed | :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 shell call. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - `class ShellCallOutput` + - `:explicit` - The streamed output items emitted by a shell tool call. + - `class BetaResponseInputFileContent` - - `call_id: String` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: :input_file` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + The type of the input item. Always `input_file`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `:input_file` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `detail: :auto | :low | :high` - The exit or timeout outcome associated with this shell 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`. - - `class Timeout` + - `:auto` - Indicates that the shell call exceeded its configured time limit. + - `:low` - - `type: :timeout` + - `:high` - The outcome type. Always `timeout`. + - `file_data: String` - - `:timeout` + The base64-encoded data of the file to be sent to the model. - - `class Exit` + - `file_id: String` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `exit_code: Integer` + - `file_url: String` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `type: :exit` + - `filename: String` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `:exit` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `stderr: 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. - Captured stderr output for the shell call. + - `mode: :explicit` - - `stdout: String` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `:explicit` - - `type: :shell_call_output` + - `type: :function_call_output` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `:shell_call_output` + - `:function_call_output` - `id: String` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -101078,13 +112399,9 @@ puts(beta_compacted_response) - `:program` - - `max_output_length: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `status: :in_progress | :completed | :incomplete` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -101092,85 +112409,97 @@ puts(beta_compacted_response) - `:incomplete` - - `class ApplyPatchCall` + - `class AgentMessage` - A tool call representing a request to create, delete, or update files using diff patches. + A message routed between agents. - - `call_id: String` + - `author: String` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class CreateFile` + - `class BetaResponseInputTextContent` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `diff: String` + - `class BetaResponseInputImageContent` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `path: String` + - `class EncryptedContent` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: :create_file` + - `encrypted_content: String` - The operation type. Always `create_file`. + Opaque encrypted content. - - `:create_file` + - `type: :encrypted_content` - - `class DeleteFile` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `:encrypted_content` - - `path: String` + - `recipient: String` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `type: :delete_file` + - `type: :agent_message` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `:delete_file` + - `:agent_message` - - `class UpdateFile` + - `id: String` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `diff: String` + - `agent: Agent{ agent_name}` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `path: String` + - `agent_name: String` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `type: :update_file` + - `class MultiAgentCall` - The operation type. Always `update_file`. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:update_file` + The multi-agent action that was executed. - - `status: :in_progress | :completed` + - `:spawn_agent` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:interrupt_agent` - - `:in_progress` + - `:list_agents` - - `:completed` + - `:send_message` - - `type: :apply_patch_call` + - `:followup_task` - The type of the item. Always `apply_patch_call`. + - `:wait_agent` - - `:apply_patch_call` + - `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: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - `agent: Agent{ agent_name}` @@ -101180,129 +112509,127 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. + - `class MultiAgentCallOutput` - - `class Direct` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `type: :direct` + The multi-agent action that produced this result. - The caller type. Always `direct`. + - `:spawn_agent` - - `:direct` + - `:interrupt_agent` - - `class Program` + - `: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. - - `class ApplyPatchCallOutput` + - `output: Array[Output{ text, type, annotations}]` - The streamed output emitted by an apply patch tool call. + Text output returned by the multi-agent action. - - `call_id: String` + - `text: String` - The unique ID of the apply patch tool call generated by the model. + The text content. - - `status: :completed | :failed` + - `type: :output_text` - The status of the apply patch tool call output. One of `completed` or `failed`. + The content type. Always `output_text`. - - `:completed` + - `:output_text` - - `:failed` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `type: :apply_patch_call_output` + Citations associated with the text content. - The type of the item. Always `apply_patch_call_output`. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `:apply_patch_call_output` + - `file_id: String` - - `id: 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: Agent{ agent_name}` + The filename of the file cited. - The agent that produced this item. + - `index: Integer` - - `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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The citation type. Always `file_citation`. - The execution context that produced this tool call. + - `:file_citation` - - `class Direct` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `type: :direct` + - `end_index: Integer` - The caller type. Always `direct`. + The index of the last character of the citation in the message. - - `:direct` + - `start_index: Integer` - - `class Program` + The index of the first character of the citation in the message. - - `caller_id: String` + - `title: String` - The call ID of the program item that produced this tool call. + The title of the cited resource. - - `type: :program` + - `type: :url_citation` - The caller type. Always `program`. + The citation type. Always `url_citation`. - - `:program` + - `:url_citation` - - `output: String` + - `url: String` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The URL of the cited resource. - - `class McpListTools` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - A list of tools available on an MCP server. + - `container_id: String` - - `id: String` + The ID of the container. - The unique ID of the list. + - `end_index: Integer` - - `server_label: String` + The index of the last character of the citation in the message. - The label of the MCP server. + - `file_id: String` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + The ID of the container file. - The tools available on the server. + - `filename: String` - - `input_schema: untyped` + The filename of the container file cited. - The JSON schema describing the tool's input. + - `start_index: Integer` - - `name: String` + The index of the first character of the citation in the message. - The name of the tool. + - `type: :container_file_citation` - - `annotations: untyped` + The citation type. Always `container_file_citation`. - Additional annotations about the tool. + - `:container_file_citation` - - `description: String` + - `type: :multi_agent_call_output` - The description of the tool. + The item type. Always `multi_agent_call_output`. - - `type: :mcp_list_tools` + - `:multi_agent_call_output` - The type of the item. Always `mcp_list_tools`. + - `id: String` - - `:mcp_list_tools` + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -101312,1097 +112639,1161 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `error: String` + - `class ToolSearchCall` - Error message if the server could not list tools. + - `arguments: untyped` - - `class McpApprovalRequest` + The arguments supplied to the tool search call. - A request for human approval of a tool invocation. + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` - `id: String` - The unique ID of the approval request. + The unique ID of this tool search call. - - `arguments: String` + - `agent: Agent{ agent_name}` - A JSON string of arguments for the tool. + The agent that produced this item. - - `name: String` + - `agent_name: String` - The name of the tool to run. + The canonical name of the agent that produced this item. - - `server_label: String` + - `call_id: String` - The label of the MCP server making the request. + The unique ID of the tool search call generated by the model. - - `type: :mcp_approval_request` + - `execution: :server | :client` - The type of the item. Always `mcp_approval_request`. + Whether tool search was executed by the server or by the client. - - `:mcp_approval_request` + - `:server` - - `agent: Agent{ agent_name}` + - `:client` - The agent that produced this item. + - `status: :in_progress | :completed | :incomplete` - - `agent_name: String` + The status of the tool search call. - The canonical name of the agent that produced this item. + - `:in_progress` - - `class McpApprovalResponse` + - `:completed` - A response to an MCP approval request. + - `:incomplete` - - `approval_request_id: String` + - `class BetaResponseToolSearchOutputItemParam` - The ID of the approval request being answered. + - `tools: Array[BetaTool]` - - `approve: bool` + The loaded tool definitions returned by the tool search output. - Whether the request was approved. + - `class BetaFunctionTool` - - `type: :mcp_approval_response` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the item. Always `mcp_approval_response`. + - `name: String` - - `:mcp_approval_response` + The name of the function to call. - - `id: String` + - `parameters: Hash[Symbol, untyped]` - The unique ID of the approval response + A JSON schema object describing the parameters of the function. - - `agent: Agent{ agent_name}` + - `strict: bool` - 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`. - - `reason: String` + - `:function` - Optional reason for the decision. + - `allowed_callers: Array[:direct | :programmatic]` - - `class McpCall` + 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: bool` - - `arguments: String` + Whether this function is deferred and loaded via tool search. - A JSON string of the arguments passed to the tool. + - `description: String` - - `name: String` + A description of the function. Used by the model to determine whether or not to call the function. - The name of the tool that was run. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool` + + 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[String]` + + The IDs of the vector stores to search. - - `server_label: String` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - The label of the MCP server running the tool. + A filter to apply. - - `type: :mcp_call` + - `class ComparisonFilter` - The type of the item. Always `mcp_call`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:mcp_call` + - `key: String` - - `agent: Agent{ agent_name}` + The key to compare against the value. - The agent that produced this item. + - `type: :eq | :ne | :gt | 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 - - `approval_request_id: String` + - `:eq` - 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. + - `:ne` - - `error: String` + - `:gt` - The error from the tool call, if any. + - `:gte` - - `output: String` + - `:lt` - The output from the tool call. + - `:lte` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `:in` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `:nin` - - `:in_progress` + - `value: String | Float | bool | Array[String | Float]` - - `:completed` + The value to compare against the attribute key; supports string, number, or boolean types. - - `:incomplete` + - `String = String` - - `:calling` + - `Float = Float` - - `:failed` + - `UnionMember2 = bool` - - `class BetaResponseCustomToolCallOutput` + - `UnionMember3 = Array[String | Float]` - The output of a custom tool call from your code, being sent back to the model. + - `String = String` - - `call_id: String` + - `Float = Float` - The call ID, used to map this custom tool call output to a custom tool call. + - `class CompoundFilter` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + Combine multiple filters using `and` or `or`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - `String = String` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A string of the output of the custom tool call. + - `class ComparisonFilter` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | 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 custom tool call. + - `key: String` - - `class BetaResponseInputText` + The key to compare against the value. - A text input to the model. + - `type: :eq | :ne | :gt | 5 more` - - `class BetaResponseInputImage` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class BetaResponseInputFile` + - `:eq` - A file input to the model. + - `:ne` - - `type: :custom_tool_call_output` + - `:gt` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `:gte` - - `:custom_tool_call_output` + - `:lt` - - `id: String` + - `:lte` - The unique ID of the custom tool call output in the OpenAI platform. + - `:in` - - `agent: Agent{ agent_name}` + - `:nin` - The agent that produced this item. + - `value: String | Float | bool | Array[String | Float]` - - `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 = String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `Float = Float` - The execution context that produced this tool call. + - `UnionMember2 = bool` - - `class Direct` + - `UnionMember3 = Array[String | Float]` - - `type: :direct` + - `String = String` - The caller type. Always `direct`. + - `Float = Float` - - `:direct` + - `UnionMember1 = untyped` - - `class Program` + - `type: :and | :or` - - `caller_id: String` + Type of operation: `and` or `or`. - The call ID of the program item that produced this tool call. + - `:and` - - `type: :program` + - `:or` - The caller type. Always `program`. + - `max_num_results: Integer` - - `:program` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `class BetaResponseCustomToolCall` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - A call to a custom tool created by the model. + Ranking options for search. - - `call_id: String` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - An identifier used to map this custom tool call to a tool call output. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `input: String` + - `embedding_weight: Float` - The input for the custom tool call generated by the model. + The weight of the embedding in the reciprocal ranking fusion. - - `name: String` + - `text_weight: Float` - The name of the custom tool being called. + The weight of the text in the reciprocal ranking fusion. - - `type: :custom_tool_call` + - `ranker: :auto | :"default-2024-11-15"` - The type of the custom tool call. Always `custom_tool_call`. + The ranker to use for the file search. - - `:custom_tool_call` + - `:auto` - - `id: String` + - `:"default-2024-11-15"` - The unique ID of the custom tool call in the OpenAI platform. + - `score_threshold: Float` - - `agent: Agent{ 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. + - `class BetaComputerTool` - - `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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The type of the computer tool. Always `computer`. - The execution context that produced this tool call. + - `:computer` - - `class Direct` + - `class BetaComputerUsePreviewTool` - - `type: :direct` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:direct` + - `display_height: Integer` - - `class Program` + The height of the computer display. - - `caller_id: String` + - `display_width: Integer` - The call ID of the program item that produced this tool call. + The width of the computer display. - - `type: :program` + - `environment: :windows | :mac | :linux | 2 more` - - `:program` + The type of computer environment to control. - - `namespace: String` + - `:windows` - The namespace of the custom tool being called. + - `:mac` - - `class CompactionTrigger` + - `:linux` - Compacts the current context. Must be the final input item. + - `:ubuntu` - - `type: :compaction_trigger` + - `:browser` - The type of the item. Always `compaction_trigger`. + - `type: :computer_use_preview` - - `:compaction_trigger` + The type of the computer use tool. Always `computer_use_preview`. - - `agent: Agent{ agent_name}` + - `:computer_use_preview` - The agent that produced this item. + - `class BetaWebSearchTool` - - `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 | :web_search_2025_08_26` - - `class ItemReference` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - An internal identifier for an item to reference. + - `:web_search` - - `id: String` + - `:web_search_2025_08_26` - The ID of the item to reference. + - `filters: Filters{ allowed_domains}` - - `agent: Agent{ agent_name}` + Filters for the search. - The agent that produced this item. + - `allowed_domains: Array[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"]` - - `type: :item_reference` + - `search_context_size: :low | :medium | :high` - The type of item to reference. Always `item_reference`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `:item_reference` + - `:low` - - `class Program` + - `:medium` - - `id: String` + - `:high` - The unique ID of this program item. + - `user_location: UserLocation{ city, country, region, 2 more}` - - `call_id: String` + The approximate location of the user. - The stable call ID of the program item. + - `city: String` - - `code: String` + Free text input for the city of the user, e.g. `San Francisco`. - The JavaScript source executed by programmatic tool calling. + - `country: String` - - `fingerprint: String` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Opaque program replay fingerprint that must be round-tripped. + - `region: String` - - `type: :program` + Free text input for the region of the user, e.g. `California`. - The item type. Always `program`. + - `timezone: String` - - `:program` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `agent: Agent{ 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. + - `class Mcp` - - `class ProgramOutput` + 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 this program output item. + A label for this MCP server, used to identify it in tool calls. - - `call_id: String` + - `type: :mcp` - The call ID of the program item. + The type of the MCP tool. Always `mcp`. - - `result: String` + - `:mcp` - The result produced by the program item. + - `allowed_callers: Array[:direct | :programmatic]` - - `status: :completed | :incomplete` + The tool invocation context(s). - The terminal status of the program output. + - `:direct` - - `:completed` + - `:programmatic` - - `:incomplete` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `type: :program_output` + List of allowed tool names or a filter object. - The item type. Always `program_output`. + - `McpAllowedTools = Array[String]` - - `:program_output` + A string array of allowed tool names - - `agent: Agent{ agent_name}` + - `class McpToolFilter` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `agent_name: String` + - `read_only: bool` - The canonical name of the agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. -### Beta Response Input Message Content List + - `tool_names: Array[String]` -- `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + List of allowed tool names. - A list of one or many input items to the model, containing different content - types. + - `authorization: String` - - `class BetaResponseInputText` + 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 text input to the model. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `text: String` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The text input to the model. + Currently supported `connector_id` values are: - - `type: :input_text` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The type of the input item. Always `input_text`. + - `:connector_dropbox` - - `:input_text` + - `:connector_gmail` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:connector_googlecalendar` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:connector_googledrive` - - `mode: :explicit` + - `:connector_microsoftteams` - The breakpoint mode. Always `explicit`. + - `:connector_outlookcalendar` - - `:explicit` + - `:connector_outlookemail` - - `class BetaResponseInputImage` + - `:connector_sharepoint` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `defer_loading: bool` - - `detail: :low | :high | :auto | :original` + Whether this MCP tool is deferred and discovered via tool search. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `headers: Hash[Symbol, String]` - - `:low` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `:high` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `:auto` + Specify which of the MCP server's tools require approval. - - `:original` + - `class McpToolApprovalFilter` - - `type: :input_image` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The type of the input item. Always `input_image`. + - `always: Always{ read_only, tool_names}` - - `:input_image` + A filter object to specify which tools are allowed. - - `file_id: String` + - `read_only: bool` - The ID of the file to be sent to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `image_url: String` + - `tool_names: Array[String]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + List of allowed tool names. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `never: Never{ read_only, tool_names}` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A filter object to specify which tools are allowed. - - `mode: :explicit` + - `read_only: bool` - The breakpoint mode. Always `explicit`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `:explicit` + - `tool_names: Array[String]` - - `class BetaResponseInputFile` + List of allowed tool names. - A file input to the model. + - `McpToolApprovalSetting = :always | :never` - - `type: :input_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 type of the input item. Always `input_file`. + - `:always` - - `:input_file` + - `:never` - - `detail: :auto | :low | :high` + - `server_description: 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`. + Optional description of the MCP server, used to provide more context. - - `:auto` + - `server_url: String` - - `:low` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `:high` + - `tunnel_id: String` - - `file_data: 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 content of the file to be sent to the model. + - `class CodeInterpreter` - - `file_id: String` + A tool that runs Python code to help generate a response to a prompt. - The ID of the file to be sent to the model. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `file_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 file to be sent to the model. + - `String = String` - - `filename: String` + The container ID. - The name of the file to be sent to the model. + - `class CodeInterpreterToolAuto` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Marks the exact end of a reusable 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: :auto` - - `mode: :explicit` + Always `auto`. - The breakpoint mode. Always `explicit`. + - `:auto` - - `:explicit` + - `file_ids: Array[String]` -### Beta Response Input Message Item + An optional list of uploaded files to make available to your code. -- `class BetaResponseInputMessageItem` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `id: String` + The memory limit for the code interpreter container. - The unique ID of the message input. + - `:"1g"` - - `content: BetaResponseInputMessageContentList` + - `:"4g"` - A list of one or many input items to the model, containing different content - types. + - `:"16g"` - - `class BetaResponseInputText` + - `:"64g"` - A text input to the model. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `text: String` + Network access policy for the container. - The text input to the model. + - `class BetaContainerNetworkPolicyDisabled` - - `type: :input_text` + - `type: :disabled` - The type of the input item. Always `input_text`. + Disable outbound network access. Always `disabled`. - - `:input_text` + - `:disabled` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class 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. + - `allowed_domains: Array[String]` - - `mode: :explicit` + A list of allowed domains when type is `allowlist`. - The breakpoint mode. Always `explicit`. + - `type: :allowlist` - - `:explicit` + Allow outbound network access only to specified domains. Always `allowlist`. - - `class BetaResponseInputImage` + - `:allowlist` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - - `detail: :low | :high | :auto | :original` + Optional domain-scoped secrets for allowlisted domains. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `domain: String` - - `:low` + The domain associated with the secret. - - `:high` + - `name: String` - - `:auto` + The name of the secret to inject for the domain. - - `:original` + - `value: String` - - `type: :input_image` + The secret value to inject for the domain. - The type of the input item. Always `input_image`. + - `type: :code_interpreter` - - `:input_image` + The type of the code interpreter tool. Always `code_interpreter`. - - `file_id: String` + - `:code_interpreter` - The ID of the file to be sent to the model. + - `allowed_callers: Array[:direct | :programmatic]` - - `image_url: String` + The tool invocation context(s). - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `:direct` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:programmatic` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class ProgrammaticToolCalling` - - `mode: :explicit` + - `type: :programmatic_tool_calling` - The breakpoint mode. Always `explicit`. + The type of the tool. Always `programmatic_tool_calling`. - - `:explicit` + - `:programmatic_tool_calling` - - `class BetaResponseInputFile` + - `class ImageGeneration` - A file input to the model. + A tool that generates images using the GPT image models. - - `type: :input_file` + - `type: :image_generation` - The type of the input item. Always `input_file`. + The type of the image generation tool. Always `image_generation`. - - `:input_file` + - `:image_generation` - - `detail: :auto | :low | :high` + - `action: :generate | :edit | :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`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `:auto` + - `:generate` - - `:low` + - `:edit` - - `:high` + - `:auto` - - `file_data: String` + - `background: :transparent | :opaque | :auto` - The content of the file to be sent to the model. + 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 ID of the file to be sent to the model. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `file_url: String` + - `:transparent` - The URL of the file to be sent to the model. + - `:opaque` - - `filename: String` + - `:auto` - The name of the file to be sent to the model. + - `input_fidelity: :high | :low` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:high` - - `mode: :explicit` + - `:low` - The breakpoint mode. Always `explicit`. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `:explicit` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `role: :user | :system | :developer` + - `file_id: String` - The role of the message input. One of `user`, `system`, or `developer`. + File ID for the mask image. - - `:user` + - `image_url: String` - - `:system` + Base64-encoded mask image. - - `:developer` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `type: :message` + The image generation model to use. Default: `gpt-image-1`. - The type of the message input. Always set to `message`. + - `String = String` - - `:message` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `agent: Agent{ agent_name}` + The image generation model to use. Default: `gpt-image-1`. - The agent that produced this item. + - `:"gpt-image-1"` - - `agent_name: String` + - `:"gpt-image-1-mini"` - The canonical name of the agent that produced this item. + - `:"gpt-image-2"` - - `status: :in_progress | :completed | :incomplete` + - `:"gpt-image-2-2026-04-21"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:"gpt-image-1.5"` - - `:in_progress` + - `:"chatgpt-image-latest"` - - `:completed` + - `moderation: :auto | :low` - - `:incomplete` + Moderation level for the generated image. Default: `auto`. -### Beta Response Input Text + - `:auto` -- `class BetaResponseInputText` + - `:low` - A text input to the model. + - `output_compression: Integer` - - `text: String` + Compression level for the output image. Default: 100. - The text input to the model. + - `output_format: :png | :webp | :jpeg` - - `type: :input_text` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the input item. Always `input_text`. + - `:png` - - `:input_text` + - `:webp` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:jpeg` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `partial_images: Integer` - - `mode: :explicit` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The breakpoint mode. Always `explicit`. + - `quality: :low | :medium | :high | :auto` - - `:explicit` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. -### Beta Response Input Text Content + - `:low` -- `class BetaResponseInputTextContent` + - `:medium` - A text input to the model. + - `:high` - - `text: String` + - `:auto` - The text input to the model. + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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`. - The type of the input item. Always `input_text`. + - `String = String` - - `:input_text` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. + - `:"1024x1024"` - - `mode: :explicit` + - `:"1024x1536"` - The breakpoint mode. Always `explicit`. + - `:"1536x1024"` - - `:explicit` + - `:auto` -### Beta Response Item + - `class LocalShell` -- `BetaResponseItem = BetaResponseInputMessageItem | BetaResponseOutputMessage | BetaResponseFileSearchToolCall | 29 more` + A tool that allows the model to execute shell commands in a local environment. - Content item used to generate a response. + - `type: :local_shell` - - `class BetaResponseInputMessageItem` + The type of the local shell tool. Always `local_shell`. - - `id: String` + - `:local_shell` - The unique ID of the message input. + - `class BetaFunctionShellTool` - - `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` - - `class BetaResponseInputText` + The type of the shell tool. Always `shell`. - A text input to the model. + - `:shell` - - `text: String` + - `allowed_callers: Array[:direct | :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` + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class BetaContainerAuto` - Marks the exact end of a reusable 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: :container_auto` - - `mode: :explicit` + Automatically creates a container for this request - The breakpoint mode. Always `explicit`. + - `:container_auto` - - `:explicit` + - `file_ids: Array[String]` - - `class BetaResponseInputImage` + An optional list of uploaded files to make available to your code. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `detail: :low | :high | :auto | :original` + The memory limit for the container. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:"1g"` - - `:low` + - `:"4g"` - - `:high` + - `:"16g"` - - `:auto` + - `:"64g"` - - `:original` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `type: :input_image` + Network access policy for the container. - The type of the input item. Always `input_image`. + - `class BetaContainerNetworkPolicyDisabled` - - `:input_image` + - `class BetaContainerNetworkPolicyAllowlist` - - `file_id: String` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - The ID of the file to be sent to the model. + An optional list of skills referenced by id or inline data. - - `image_url: String` + - `class BetaSkillReference` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `skill_id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The ID of the referenced skill. - Marks the exact end of a reusable 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: :skill_reference` - - `mode: :explicit` + References a skill created with the /v1/skills endpoint. - The breakpoint mode. Always `explicit`. + - `:skill_reference` - - `:explicit` + - `version: String` - - `class BetaResponseInputFile` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A file input to the model. + - `class BetaInlineSkill` - - `type: :input_file` + - `description: String` - The type of the input item. Always `input_file`. + The description of the skill. - - `:input_file` + - `name: String` - - `detail: :auto | :low | :high` + The name of the skill. - 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`. + - `source: BetaInlineSkillSource` - - `:auto` + Inline skill payload - - `:low` + - `data: String` - - `:high` + Base64-encoded skill zip bundle. - - `file_data: String` + - `media_type: :"application/zip"` - The content of the file to be sent to the model. + The media type of the inline skill payload. Must be `application/zip`. - - `file_id: String` + - `:"application/zip"` - The ID of the file to be sent to the model. + - `type: :base64` - - `file_url: String` + The type of the inline skill source. Must be `base64`. - The URL of the file to be sent to the model. + - `:base64` - - `filename: String` + - `type: :inline` - The name of the file to be sent to the model. + Defines an inline skill for this request. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:inline` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaLocalEnvironment` - - `mode: :explicit` + - `type: :local` - The breakpoint mode. Always `explicit`. + Use a local computer environment. - - `:explicit` + - `:local` - - `role: :user | :system | :developer` + - `skills: Array[BetaLocalSkill]` - The role of the message input. One of `user`, `system`, or `developer`. + An optional list of skills. - - `:user` + - `description: String` - - `:system` + The description of the skill. - - `:developer` + - `name: String` - - `type: :message` + The name of the skill. - The type of the message input. Always set to `message`. + - `path: String` - - `:message` + The path to the directory containing the skill. - - `agent: Agent{ agent_name}` + - `class BetaContainerReference` - The agent that produced this item. + - `container_id: String` - - `agent_name: String` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: :container_reference` - - `status: :in_progress | :completed | :incomplete` + References a container created with the /v1/containers endpoint - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:container_reference` - - `:in_progress` + - `class BetaCustomTool` - - `: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` - - `class BetaResponseOutputMessage` + The name of the custom tool, used to identify it in tool calls. - An output message from the model. + - `type: :custom` - - `id: String` + The type of the custom tool. Always `custom`. - The unique ID of the output message. + - `:custom` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `allowed_callers: Array[:direct | :programmatic]` - The content of the output message. + The tool invocation context(s). - - `class BetaResponseOutputText` + - `:direct` - A text output from the model. + - `:programmatic` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `defer_loading: bool` - The annotations of the text output. + Whether this tool should be deferred and discovered via tool search. - - `class FileCitation` + - `description: String` - A citation to a file. + Optional description of the custom tool, used to provide more context. - - `file_id: String` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - The ID of the file. + The input format for the custom tool. Default is unconstrained text. - - `filename: String` + - `class Text` - The filename of the file cited. + Unconstrained free-form text. - - `index: Integer` + - `type: :text` - The index of the file in the list of files. + Unconstrained text format. Always `text`. - - `type: :file_citation` + - `:text` - The type of the file citation. Always `file_citation`. + - `class Grammar` - - `:file_citation` + A grammar defined by the user. - - `class URLCitation` + - `definition: String` - A citation for a web resource used to generate a model response. + The grammar definition. - - `end_index: Integer` + - `syntax: :lark | :regex` - The index of the last character of the URL citation in the message. + The syntax of the grammar definition. One of `lark` or `regex`. - - `start_index: Integer` + - `:lark` - The index of the first character of the URL citation in the message. + - `:regex` - - `title: String` + - `type: :grammar` - The title of the web resource. + Grammar format. Always `grammar`. - - `type: :url_citation` + - `:grammar` - The type of the URL citation. Always `url_citation`. + - `class BetaNamespaceTool` - - `:url_citation` + Groups function/custom tools under a shared namespace. - - `url: String` + - `description: String` - The URL of the web resource. + A description of the namespace shown to the model. - - `class ContainerFileCitation` + - `name: String` - A citation for a container file used to generate a model response. + The namespace name used in tool calls (for example, `crm`). - - `container_id: String` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - The ID of the container file. + The function/custom tools available inside this namespace. - - `end_index: Integer` + - `class Function` - The index of the last character of the container file citation in the message. + - `name: String` - - `file_id: String` + - `type: :function` - The ID of the file. + - `:function` - - `filename: String` + - `allowed_callers: Array[:direct | :programmatic]` - The filename of the container file cited. + The tool invocation context(s). - - `start_index: Integer` + - `:direct` - The index of the first character of the container file citation in the message. + - `:programmatic` - - `type: :container_file_citation` + - `defer_loading: bool` - The type of the container file citation. Always `container_file_citation`. + Whether this function should be deferred and discovered via tool search. - - `:container_file_citation` + - `description: String` - - `class FilePath` + - `output_schema: Hash[Symbol, untyped]` - A path to a file. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `file_id: String` + - `parameters: untyped` - The ID of the file. + - `strict: bool` - - `index: Integer` + 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 file in the list of files. + - `class BetaCustomTool` - - `type: :file_path` + 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 file path. Always `file_path`. + - `type: :namespace` - - `:file_path` + The type of the tool. Always `namespace`. - - `text: String` + - `:namespace` - The text output from the model. + - `class BetaToolSearchTool` - - `type: :output_text` + Hosted or BYOT tool search configuration for deferred tools. - The type of the output text. Always `output_text`. + - `type: :tool_search` - - `:output_text` + The type of the tool. Always `tool_search`. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:tool_search` - - `token: String` + - `description: String` - - `bytes: Array[Integer]` + Description shown to the model for a client-executed tool search tool. - - `logprob: Float` + - `execution: :server | :client` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + Whether tool search is executed by the server or by the client. - - `token: String` + - `:server` - - `bytes: Array[Integer]` + - `:client` - - `logprob: Float` + - `parameters: untyped` - - `class BetaResponseOutputRefusal` + Parameter schema for a client-executed tool search tool. - A refusal from the model. + - `class BetaWebSearchPreviewTool` - - `refusal: 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 refusal explanation from the model. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `type: :refusal` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the refusal. Always `refusal`. + - `:web_search_preview` - - `:refusal` + - `:web_search_preview_2025_03_11` - - `role: :assistant` + - `search_content_types: Array[:text | :image]` - The role of the output message. Always `assistant`. + - `:text` - - `:assistant` + - `:image` - - `status: :in_progress | :completed | :incomplete` + - `search_context_size: :low | :medium | :high` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `:in_progress` + - `:low` - - `:completed` + - `:medium` - - `:incomplete` + - `:high` - - `type: :message` + - `user_location: UserLocation{ type, city, country, 2 more}` - The type of the output message. Always `message`. + The user's location. - - `:message` + - `type: :approximate` - - `agent: Agent{ agent_name}` + The type of location approximation. Always `approximate`. - The agent that produced this item. + - `:approximate` - - `agent_name: String` + - `city: String` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `phase: :commentary` + - `country: 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 two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `:commentary` + - `region: String` - - `class BetaResponseFileSearchToolCall` + Free text input for the region of the user, e.g. `California`. - 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. + - `timezone: String` - - `id: String` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the file search tool call. + - `class BetaApplyPatchTool` - - `queries: Array[String]` + Allows the assistant to create, delete, or update files using unified diffs. - The queries used to search for files. + - `type: :apply_patch` - - `status: :in_progress | :searching | :completed | 2 more` + The type of the tool. Always `apply_patch`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `:apply_patch` - - `:in_progress` + - `allowed_callers: Array[:direct | :programmatic]` - - `:searching` + The tool invocation context(s). - - `:completed` + - `:direct` - - `:incomplete` + - `:programmatic` - - `:failed` + - `type: :tool_search_output` - - `type: :file_search_call` + The item type. Always `tool_search_output`. - The type of the file search tool call. Always `file_search_call`. + - `:tool_search_output` - - `:file_search_call` + - `id: String` + + The unique ID of this tool search output. - `agent: Agent{ agent_name}` @@ -102412,321 +113803,323 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `call_id: String` - The results of the file search tool call. + The unique ID of the tool search call generated by the model. - - `attributes: Hash[Symbol, String | Float | bool]` + - `execution: :server | :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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + Whether tool search was executed by the server or by the client. - - `String = String` + - `:server` - - `Float = Float` + - `:client` - - `UnionMember2 = bool` + - `status: :in_progress | :completed | :incomplete` - - `file_id: String` + The status of the tool search output. - The unique ID of the file. + - `:in_progress` - - `filename: String` + - `:completed` - The name of the file. + - `:incomplete` - - `score: Float` + - `class AdditionalTools` - The relevance score of the file - a value between 0 and 1. + - `role: :developer` - - `text: String` + The role that provided the additional tools. Only `developer` is supported. - The text that was retrieved from the file. + - `:developer` - - `class BetaResponseComputerToolCall` + - `tools: Array[BetaTool]` - 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 list of additional tools made available at this item. - - `id: String` + - `class BetaFunctionTool` - The unique ID of the 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). - - `call_id: String` + - `class BetaFileSearchTool` - An identifier used when responding to the tool call with 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). - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `class BetaComputerTool` - The pending safety checks for the computer call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: String` + - `class BetaComputerUsePreviewTool` - The ID of the pending safety check. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `code: String` + - `class BetaWebSearchTool` - The type of the pending safety check. + 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). - - `message: String` + - `class Mcp` - Details about the pending safety check. + 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). - - `status: :in_progress | :completed | :incomplete` + - `class CodeInterpreter` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool that runs Python code to help generate a response to a prompt. - - `:in_progress` + - `class ProgrammaticToolCalling` - - `:completed` + - `class ImageGeneration` - - `:incomplete` + A tool that generates images using the GPT image models. - - `type: :computer_call` + - `class LocalShell` - The type of the computer call. Always `computer_call`. + A tool that allows the model to execute shell commands in a local environment. - - `:computer_call` + - `class BetaFunctionShellTool` - - `action: BetaComputerAction` + A tool that allows the model to execute shell commands. - A click action. + - `class BetaCustomTool` - - `class Click` + 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 click action. + - `class BetaNamespaceTool` - - `button: :left | :right | :wheel | 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`. + - `class BetaToolSearchTool` - - `:left` + Hosted or BYOT tool search configuration for deferred tools. - - `:right` + - `class BetaWebSearchPreviewTool` - - `:wheel` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `:back` + - `class BetaApplyPatchTool` - - `:forward` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: :click` + - `type: :additional_tools` - Specifies the event type. For a click action, this property is always `click`. + The item type. Always `additional_tools`. - - `:click` + - `:additional_tools` - - `x: Integer` + - `id: String` - The x-coordinate where the click occurred. + The unique ID of this additional tools item. - - `y_: Integer` + - `agent: Agent{ agent_name}` - The y-coordinate where the click occurred. + The agent that produced this item. - - `keys: Array[String]` + - `agent_name: String` - The keys being held while clicking. + The canonical name of the agent that produced this item. - - `class DoubleClick` + - `class BetaResponseReasoningItem` - A double click action. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `keys: Array[String]` + - `id: String` - The keys being held while double-clicking. + The unique identifier of the reasoning content. - - `type: :double_click` + - `summary: Array[Summary{ text, type}]` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Reasoning summary content. - - `:double_click` + - `text: String` - - `x: Integer` + A summary of the reasoning output from the model so far. - The x-coordinate where the double click occurred. + - `type: :summary_text` - - `y_: Integer` + The type of the object. Always `summary_text`. - The y-coordinate where the double click occurred. + - `:summary_text` - - `class Drag` + - `type: :reasoning` - A drag action. + The type of the object. Always `reasoning`. - - `path: Array[Path{ x, y_}]` + - `:reasoning` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `agent: Agent{ agent_name}` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The agent that produced this item. - - `x: Integer` + - `agent_name: String` - The x-coordinate. + The canonical name of the agent that produced this item. - - `y_: Integer` + - `content: Array[Content{ text, type}]` - The y-coordinate. + Reasoning text content. - - `type: :drag` + - `text: String` - Specifies the event type. For a drag action, this property is always set to `drag`. + The reasoning text from the model. - - `:drag` + - `type: :reasoning_text` - - `keys: Array[String]` + The type of the reasoning text. Always `reasoning_text`. - The keys being held while dragging the mouse. + - `:reasoning_text` - - `class Keypress` + - `encrypted_content: String` - A collection of keypresses the model would like to perform. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `keys: Array[String]` + - `status: :in_progress | :completed | :incomplete` - 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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: :keypress` + - `:in_progress` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `:completed` - - `:keypress` + - `:incomplete` - - `class Move` + - `class BetaResponseCompactionItemParam` - A mouse move action. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `type: :move` + - `encrypted_content: String` - Specifies the event type. For a move action, this property is always set to `move`. + The encrypted content of the compaction summary. - - `:move` + - `type: :compaction` - - `x: Integer` + The type of the item. Always `compaction`. - The x-coordinate to move to. + - `:compaction` - - `y_: Integer` + - `id: String` - The y-coordinate to move to. + The ID of the compaction item. - - `keys: Array[String]` + - `agent: Agent{ agent_name}` - The keys being held while moving the mouse. + The agent that produced this item. - - `class Screenshot` + - `agent_name: String` - A screenshot action. + The canonical name of the agent that produced this item. - - `type: :screenshot` + - `class ImageGenerationCall` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + An image generation request made by the model. - - `:screenshot` + - `id: String` - - `class Scroll` + The unique ID of the image generation call. - A scroll action. + - `result: String` - - `scroll_x: Integer` + The generated image encoded in base64. - The horizontal scroll distance. + - `status: :in_progress | :completed | :generating | :failed` - - `scroll_y: Integer` + The status of the image generation call. - The vertical scroll distance. + - `:in_progress` - - `type: :scroll` + - `:completed` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `:generating` - - `:scroll` + - `:failed` - - `x: Integer` + - `type: :image_generation_call` - The x-coordinate where the scroll occurred. + The type of the image generation call. Always `image_generation_call`. - - `y_: Integer` + - `:image_generation_call` - The y-coordinate where the scroll occurred. + - `agent: Agent{ agent_name}` - - `keys: Array[String]` + The agent that produced this item. - The keys being held while scrolling. + - `agent_name: String` - - `class Type` + The canonical name of the agent that produced this item. - An action to type in text. + - `class BetaResponseCodeInterpreterToolCall` - - `text: String` + A tool call to run code. - The text to type. + - `id: String` - - `type: :type` + The unique ID of the code interpreter tool call. - Specifies the event type. For a type action, this property is always set to `type`. + - `code: String` - - `:type` + The code to run, or null if not available. - - `class Wait` + - `container_id: String` - A wait action. + The ID of the container used to run the code. - - `type: :wait` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - Specifies the event type. For a wait action, this property is always set to `wait`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `:wait` + - `class Logs` - - `actions: BetaComputerActionList` + The logs output from the code interpreter. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `logs: String` - - `class Click` + The logs output from the code interpreter. - A click action. + - `type: :logs` - - `class DoubleClick` + The type of the output. Always `logs`. - A double click action. + - `:logs` - - `class Drag` + - `class Image` - A drag action. + The image output from the code interpreter. - - `class Keypress` + - `type: :image` - A collection of keypresses the model would like to perform. + The type of the output. Always `image`. - - `class Move` + - `:image` - A mouse move action. + - `url: String` - - `class Screenshot` + The URL of the image output from the code interpreter. - A screenshot action. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `class Scroll` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - A scroll action. + - `:in_progress` - - `class Type` + - `:completed` - An action to type in text. + - `:incomplete` - - `class Wait` + - `:interpreting` - A wait action. + - `:failed` + + - `type: :code_interpreter_call` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `:code_interpreter_call` - `agent: Agent{ agent_name}` @@ -102736,70 +114129,63 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem` - - - `id: String` - - The unique ID of the computer call tool output. + - `class LocalShellCall` - - `call_id: String` + A tool call to run a command on the local shell. - The ID of the computer tool call that produced the output. + - `id: String` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The unique ID of the local shell call. - A computer screenshot image used with the computer use tool. + - `action: Action{ command, env, type, 3 more}` - - `type: :computer_screenshot` + Execute a shell command on the server. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `command: Array[String]` - - `:computer_screenshot` + The command to run. - - `file_id: String` + - `env: Hash[Symbol, String]` - The identifier of an uploaded file that contains the screenshot. + Environment variables to set for the command. - - `image_url: String` + - `type: :exec` - The URL of the screenshot image. + The type of the local shell action. Always `exec`. - - `status: :completed | :incomplete | :failed | :in_progress` + - `:exec` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `timeout_ms: Integer` - - `:completed` + Optional timeout in milliseconds for the command. - - `:incomplete` + - `user: String` - - `:failed` + Optional user to run the command as. - - `:in_progress` + - `working_directory: String` - - `type: :computer_call_output` + Optional working directory to run the command in. - The type of the computer tool call output. Always `computer_call_output`. + - `call_id: String` - - `:computer_call_output` + The unique ID of the local shell tool call generated by the model. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `status: :in_progress | :completed | :incomplete` - The safety checks reported by the API that have been acknowledged by the - developer. + The status of the local shell call. - - `id: String` + - `:in_progress` - The ID of the pending safety check. + - `:completed` - - `code: String` + - `:incomplete` - The type of the pending safety check. + - `type: :local_shell_call` - - `message: String` + The type of the local shell call. Always `local_shell_call`. - Details about the pending safety check. + - `:local_shell_call` - `agent: Agent{ agent_name}` @@ -102809,127 +114195,119 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseFunctionWebSearch` + - `class LocalShellCallOutput` - 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 output of a local shell tool call. - `id: String` - The unique ID of the web search tool call. + The unique ID of the local shell tool call generated by the model. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `output: String` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A JSON string of the output of the local shell tool call. - - `class Search` + - `type: :local_shell_call_output` - Action type "search" - Performs a web search query. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `type: :search` + - `:local_shell_call_output` - The action type. + - `agent: Agent{ agent_name}` - - `:search` + The agent that produced this item. - - `queries: Array[String]` + - `agent_name: String` - The search queries. + The canonical name of the agent that produced this item. - - `query: String` + - `status: :in_progress | :completed | :incomplete` - The search query. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `sources: Array[Source{ type, url}]` + - `:in_progress` - The sources used in the search. + - `:completed` - - `type: :url` + - `:incomplete` - The type of source. Always `url`. + - `class ShellCall` - - `:url` + A tool representing a request to execute one or more shell commands. - - `url: String` + - `action: Action{ commands, max_output_length, timeout_ms}` - The URL of the source. + The shell commands and limits that describe how to run the tool call. - - `class OpenPage` + - `commands: Array[String]` - Action type "open_page" - Opens a specific URL from search results. + Ordered shell commands for the execution environment to run. - - `type: :open_page` + - `max_output_length: Integer` - The action type. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `:open_page` + - `timeout_ms: Integer` - - `url: String` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The URL opened by the model. + - `call_id: String` - - `class FindInPage` + The unique ID of the shell tool call generated by the model. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: :shell_call` - - `pattern: String` + The type of the item. Always `shell_call`. - The pattern or text to search for within the page. + - `:shell_call` - - `type: :find_in_page` + - `id: String` - The action type. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `:find_in_page` + - `agent: Agent{ agent_name}` - - `url: String` + The agent that produced this item. - The URL of the page searched for the pattern. + - `agent_name: String` - - `status: :in_progress | :searching | :completed | :failed` + The canonical name of the agent that produced this item. - The status of the web search tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:in_progress` + The execution context that produced this tool call. - - `:searching` + - `class Direct` - - `:completed` + - `type: :direct` - - `:failed` + The caller type. Always `direct`. - - `type: :web_search_call` + - `:direct` - The type of the web search tool call. Always `web_search_call`. + - `class Program` - - `:web_search_call` + - `caller_id: String` - - `agent: Agent{ 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` - - `class BetaResponseFunctionToolCallItem` + - `environment: BetaLocalEnvironment | BetaContainerReference` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The environment to execute the shell commands in. - - `id: String` + - `class BetaLocalEnvironment` - The unique ID of the function tool call. + - `class BetaContainerReference` - `status: :in_progress | :completed | :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. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` @@ -102937,61 +114315,63 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` + - `class ShellCallOutput` - The identifier of the actor that created the item. + The streamed output items emitted by a shell tool call. - - `class BetaResponseFunctionToolCallOutputItem` + - `call_id: String` - - `id: String` + The unique ID of the shell tool call generated by the model. - The unique ID of the function call tool output. + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - - `call_id: String` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The unique ID of the function tool call generated by the model. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The exit or timeout outcome associated with this shell call. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `class Timeout` - - `String = String` + Indicates that the shell call exceeded its configured time limit. - A string of the output of the function call. + - `type: :timeout` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The outcome type. Always `timeout`. - Text, image, or file output of the function call. + - `:timeout` - - `class BetaResponseInputText` + - `class Exit` - A text input to the model. + Indicates that the shell commands finished and returned an exit code. - - `class BetaResponseInputImage` + - `exit_code: Integer` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The exit code returned by the shell process. - - `class BetaResponseInputFile` + - `type: :exit` - A file input to the model. + The outcome type. Always `exit`. - - `status: :in_progress | :completed | :incomplete` + - `:exit` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `stderr: String` - - `:in_progress` + Captured stderr output for the shell call. - - `:completed` + - `stdout: String` - - `:incomplete` + Captured stdout output for the shell call. - - `type: :function_call_output` + - `type: :shell_call_output` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `shell_call_output`. - - `:function_call_output` + - `:shell_call_output` + + - `id: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -103025,247 +114405,231 @@ puts(beta_compacted_response) - `:program` - - `created_by: String` - - The identifier of the actor that created the item. + - `max_output_length: Integer` - - `class AgentMessage` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `id: String` + - `status: :in_progress | :completed | :incomplete` - The unique ID of the agent message. + The status of the shell call output. - - `author: String` + - `:in_progress` - The sending agent identity. + - `:completed` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `:incomplete` - Encrypted content sent between agents. + - `class ApplyPatchCall` - - `class BetaResponseInputText` + A tool call representing a request to create, delete, or update files using diff patches. - A text input to the model. + - `call_id: String` - - `class BetaResponseOutputText` + The unique ID of the apply patch tool call generated by the model. - A text output from the model. + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `class Text` + The specific create, delete, or update instruction for the apply_patch tool call. - A text content. + - `class CreateFile` - - `text: String` + Instruction for creating a new file via the apply_patch tool. - - `type: :text` + - `diff: String` - - `:text` + Unified diff content to apply when creating the file. - - `class SummaryText` + - `path: String` - A summary text from the model. + Path of the file to create relative to the workspace root. - - `text: String` + - `type: :create_file` - A summary of the reasoning output from the model so far. + The operation type. Always `create_file`. - - `type: :summary_text` + - `:create_file` - The type of the object. Always `summary_text`. + - `class DeleteFile` - - `:summary_text` + Instruction for deleting an existing file via the apply_patch tool. - - `class ReasoningText` + - `path: String` - Reasoning text from the model. + Path of the file to delete relative to the workspace root. - - `text: String` + - `type: :delete_file` - The reasoning text from the model. + The operation type. Always `delete_file`. - - `type: :reasoning_text` + - `:delete_file` - The type of the reasoning text. Always `reasoning_text`. + - `class UpdateFile` - - `:reasoning_text` + Instruction for updating an existing file via the apply_patch tool. - - `class BetaResponseOutputRefusal` + - `diff: String` - A refusal from the model. + Unified diff content to apply to the existing file. - - `class BetaResponseInputImage` + - `path: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Path of the file to update relative to the workspace root. - - `class ComputerScreenshot` + - `type: :update_file` - A screenshot of a computer. + The operation type. Always `update_file`. - - `detail: :low | :high | :auto | :original` + - `:update_file` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `status: :in_progress | :completed` - - `:low` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:high` + - `:in_progress` - - `:auto` + - `:completed` - - `:original` + - `type: :apply_patch_call` - - `file_id: String` + The type of the item. Always `apply_patch_call`. - The identifier of an uploaded file that contains the screenshot. + - `:apply_patch_call` - - `image_url: String` + - `id: String` - The URL of the screenshot image. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `type: :computer_screenshot` + - `agent: Agent{ 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` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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_: Direct{ type} | Program{ caller_id, type}` - - `mode: :explicit` + The execution context that produced this tool call. - The breakpoint mode. Always `explicit`. + - `class Direct` - - `:explicit` + - `type: :direct` - - `class BetaResponseInputFile` + The caller type. Always `direct`. - A file input to the model. + - `:direct` - - `class EncryptedContent` + - `class Program` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `caller_id: String` - - `encrypted_content: String` + The call ID of the program item that produced this tool call. - Opaque encrypted content. + - `type: :program` - - `type: :encrypted_content` + The caller type. Always `program`. - The type of the input item. Always `encrypted_content`. + - `:program` - - `:encrypted_content` + - `class ApplyPatchCallOutput` - - `recipient: String` + The streamed output emitted by an apply patch tool call. - The destination agent identity. + - `call_id: String` - - `type: :agent_message` + The unique ID of the apply patch tool call generated by the model. - The type of the item. Always `agent_message`. + - `status: :completed | :failed` - - `:agent_message` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `agent: Agent{ agent_name}` + - `:completed` - The agent that produced this item. + - `:failed` - - `agent_name: String` + - `type: :apply_patch_call_output` - The canonical name of the agent that produced this item. + The type of the item. Always `apply_patch_call_output`. - - `class MultiAgentCall` + - `:apply_patch_call_output` - `id: String` - The unique ID of the multi-agent call item. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `agent: Agent{ agent_name}` - The multi-agent action to execute. + 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` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:send_message` + The execution context that produced this tool call. - - `:followup_task` + - `class Direct` - - `:wait_agent` + - `type: :direct` - - `arguments: String` + The caller type. Always `direct`. - The JSON string of arguments generated for the action. + - `:direct` - - `call_id: String` + - `class Program` - The unique ID linking this call to its output. + - `caller_id: String` - - `type: :multi_agent_call` + The call ID of the program item that produced this tool call. - The type of the multi-agent call. Always `multi_agent_call`. + - `type: :program` - - `:multi_agent_call` + The caller type. Always `program`. - - `agent: Agent{ agent_name}` + - `:program` - The agent that produced this item. + - `output: String` - - `agent_name: String` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The canonical name of the agent that produced this item. + - `class McpListTools` - - `class MultiAgentCallOutput` + A list of tools available on an MCP server. - `id: String` - The unique ID of the multi-agent call output item. - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action that produced this result. - - - `:spawn_agent` - - - `:interrupt_agent` - - - `:list_agents` - - - `:send_message` - - - `:followup_task` + The unique ID of the list. - - `:wait_agent` + - `server_label: String` - - `call_id: String` + The label of the MCP server. - The unique ID of the multi-agent call. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `output: Array[BetaResponseOutputText]` + The tools available on the server. - Text output returned by the multi-agent action. + - `input_schema: untyped` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The JSON schema describing the tool's input. - The annotations of the text output. + - `name: String` - - `text: String` + The name of the tool. - The text output from the model. + - `annotations: untyped` - - `type: :output_text` + Additional annotations about the tool. - The type of the output text. Always `output_text`. + - `description: String` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The description of the tool. - - `type: :multi_agent_call_output` + - `type: :mcp_list_tools` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the item. Always `mcp_list_tools`. - - `:multi_agent_call_output` + - `:mcp_list_tools` - `agent: Agent{ agent_name}` @@ -103275,43 +114639,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall` - - - `id: String` - - The unique ID of the tool search call item. - - - `arguments: untyped` - - Arguments used for the tool search call. + - `error: String` - - `call_id: String` + Error message if the server could not list tools. - The unique ID of the tool search call generated by the model. + - `class McpApprovalRequest` - - `execution: :server | :client` + A request for human approval of a tool invocation. - Whether tool search was executed by the server or by the client. + - `id: String` - - `:server` + The unique ID of the approval request. - - `:client` + - `arguments: String` - - `status: :in_progress | :completed | :incomplete` + A JSON string of arguments for the tool. - The status of the tool search call item that was recorded. + - `name: String` - - `:in_progress` + The name of the tool to run. - - `:completed` + - `server_label: String` - - `:incomplete` + The label of the MCP server making the request. - - `type: :tool_search_call` + - `type: :mcp_approval_request` - The type of the item. Always `tool_search_call`. + The type of the item. Always `mcp_approval_request`. - - `:tool_search_call` + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -103321,1133 +114677,1106 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `class McpApprovalResponse` - The identifier of the actor that created the item. + A response to an MCP approval request. - - `class BetaResponseToolSearchOutputItem` + - `approval_request_id: String` - - `id: String` + The ID of the approval request being answered. - The unique ID of the tool search output item. + - `approve: bool` - - `call_id: String` + Whether the request was approved. - The unique ID of the tool search call generated by the model. + - `type: :mcp_approval_response` - - `execution: :server | :client` + The type of the item. Always `mcp_approval_response`. - Whether tool search was executed by the server or by the client. + - `:mcp_approval_response` - - `:server` + - `id: String` - - `:client` + The unique ID of the approval response - - `status: :in_progress | :completed | :incomplete` + - `agent: Agent{ 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` + - `reason: String` - - `tools: Array[BetaTool]` + Optional reason for the decision. - The loaded tool definitions returned by tool search. + - `class McpCall` - - `class BetaFunctionTool` + An invocation of a tool on an MCP server. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `id: String` - - `name: String` + The unique ID of the tool call. - The name of the function to call. + - `arguments: String` - - `parameters: Hash[Symbol, untyped]` + A JSON string of the arguments passed to the tool. - A JSON schema object describing the parameters of the function. + - `name: String` - - `strict: bool` + The name of the tool that was run. - Whether strict parameter validation is enforced for this function tool. + - `server_label: String` - - `type: :function` + The label of the MCP server running the tool. - The type of the function tool. Always `function`. + - `type: :mcp_call` - - `:function` + The type of the item. Always `mcp_call`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:mcp_call` - The tool invocation context(s). + - `agent: Agent{ agent_name}` - - `:direct` + The agent that produced this item. - - `:programmatic` + - `agent_name: String` - - `defer_loading: bool` + The canonical name of the agent that produced this item. - Whether this function is deferred and loaded via tool search. + - `approval_request_id: String` - - `description: String` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - A description of the function. Used by the model to determine whether or not to call the function. + - `error: String` - - `output_schema: Hash[Symbol, untyped]` + The error from the tool call, if any. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `output: String` - - `class BetaFileSearchTool` + The output from 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). + - `status: :in_progress | :completed | :incomplete | 2 more` - - `type: :file_search` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the file search tool. Always `file_search`. + - `:in_progress` - - `:file_search` + - `:completed` - - `vector_store_ids: Array[String]` + - `:incomplete` - The IDs of the vector stores to search. + - `:calling` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `:failed` - A filter to apply. + - `class BetaResponseCustomToolCallOutput` - - `class ComparisonFilter` + The output of a custom tool call from your code, being sent back to the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `call_id: String` - - `key: String` + The call ID, used to map this custom tool call output to a custom tool call. - The key to compare against the value. + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `type: :eq | :ne | :gt | 5 more` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `String = 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 string of the output of the custom tool call. - - `:eq` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:ne` + Text, image, or file output of the custom tool call. - - `:gt` + - `class BetaResponseInputText` - - `:gte` + A text input to the model. - - `:lt` + - `class BetaResponseInputImage` - - `:lte` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:in` + - `class BetaResponseInputFile` - - `:nin` + A file input to the model. - - `value: String | Float | bool | Array[untyped]` + - `type: :custom_tool_call_output` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `String = String` + - `:custom_tool_call_output` - - `Float = Float` + - `id: String` - - `UnionMember2 = bool` + The unique ID of the custom tool call output in the OpenAI platform. - - `UnionMember3 = Array[untyped]` + - `agent: Agent{ agent_name}` - - `class CompoundFilter` + The agent that produced this item. - Combine multiple filters using `and` or `or`. + - `agent_name: String` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The canonical name of the agent that produced this item. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class ComparisonFilter` + The execution context that produced this tool call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class Direct` - - `key: String` + - `type: :direct` - The key to compare against the value. + The caller type. Always `direct`. - - `type: :eq | :ne | :gt | 5 more` + - `:direct` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class 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 + - `caller_id: String` - - `:eq` + The call ID of the program item that produced this tool call. - - `:ne` + - `type: :program` - - `:gt` + The caller type. Always `program`. - - `:gte` + - `:program` - - `:lt` + - `class BetaResponseCustomToolCall` - - `:lte` + A call to a custom tool created by the model. - - `:in` + - `call_id: String` - - `:nin` + An identifier used to map this custom tool call to a tool call output. - - `value: String | Float | bool | Array[untyped]` + - `input: String` - The value to compare against the attribute key; supports string, number, or boolean types. + The input for the custom tool call generated by the model. - - `String = String` + - `name: String` - - `Float = Float` + The name of the custom tool being called. - - `UnionMember2 = bool` + - `type: :custom_tool_call` - - `UnionMember3 = Array[untyped]` + The type of the custom tool call. Always `custom_tool_call`. - - `UnionMember1 = untyped` + - `:custom_tool_call` - - `type: :and | :or` + - `id: String` - Type of operation: `and` or `or`. + The unique ID of the custom tool call in the OpenAI platform. - - `:and` + - `agent: Agent{ agent_name}` - - `:or` + The agent that produced this item. - - `max_num_results: Integer` + - `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: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Ranking options for search. + The execution context that produced this tool call. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `class Direct` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: :direct` - - `embedding_weight: Float` + - `:direct` - The weight of the embedding in the reciprocal ranking fusion. + - `class Program` - - `text_weight: Float` + - `caller_id: String` - The weight of the text in the reciprocal ranking fusion. + The call ID of the program item that produced this tool call. - - `ranker: :auto | :"default-2024-11-15"` + - `type: :program` - The ranker to use for the file search. + - `:program` - - `:auto` + - `namespace: String` - - `:"default-2024-11-15"` + The namespace of the custom tool being called. - - `score_threshold: Float` + - `class CompactionTrigger` - 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. + Compacts the current context. Must be the final input item. - - `class BetaComputerTool` + - `type: :compaction_trigger` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the item. Always `compaction_trigger`. - - `type: :computer` + - `:compaction_trigger` - The type of the computer tool. Always `computer`. + - `agent: Agent{ agent_name}` - - `:computer` + The agent that produced this item. - - `class BetaComputerUsePreviewTool` + - `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: Integer` + - `class ItemReference` - The height of the computer display. + An internal identifier for an item to reference. - - `display_width: Integer` + - `id: String` - The width of the computer display. + The ID of the item to reference. - - `environment: :windows | :mac | :linux | 2 more` + - `agent: Agent{ agent_name}` - The type of computer environment to control. + The agent that produced this item. - - `:windows` + - `agent_name: String` - - `:mac` + The canonical name of the agent that produced this item. - - `:linux` + - `type: :item_reference` - - `:ubuntu` + The type of item to reference. Always `item_reference`. - - `:browser` + - `:item_reference` - - `type: :computer_use_preview` + - `class Program` - The type of the computer use tool. Always `computer_use_preview`. + - `id: String` - - `:computer_use_preview` + The unique ID of this program item. - - `class BetaWebSearchTool` + - `call_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 stable call ID of the program item. - - `type: :web_search | :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 JavaScript source executed by programmatic tool calling. - - `:web_search` + - `fingerprint: String` - - `:web_search_2025_08_26` + Opaque program replay fingerprint that must be round-tripped. - - `filters: Filters{ allowed_domains}` + - `type: :program` - Filters for the search. + The item type. Always `program`. - - `allowed_domains: Array[String]` + - `:program` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `agent: Agent{ agent_name}` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The agent that produced this item. - - `search_context_size: :low | :medium | :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` + - `class ProgramOutput` - - `:medium` + - `id: String` - - `:high` + The unique ID of this program output item. - - `user_location: UserLocation{ city, country, region, 2 more}` + - `call_id: String` - The approximate location of the user. + The call ID of the program item. - - `city: String` + - `result: String` - Free text input for the city of the user, e.g. `San Francisco`. + The result produced by the program item. - - `country: String` + - `status: :completed | :incomplete` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The terminal status of the program output. - - `region: String` + - `:completed` - Free text input for the region of the user, e.g. `California`. + - `:incomplete` - - `timezone: String` + - `type: :program_output` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The item type. Always `program_output`. - - `type: :approximate` + - `:program_output` - The type of location approximation. Always `approximate`. + - `agent: Agent{ agent_name}` - - `:approximate` + The agent that produced this item. - - `class Mcp` + - `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` + - `metadata: Hash[Symbol, String]` - A label for this MCP server, used to identify it in tool calls. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `type: :mcp` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the MCP tool. Always `mcp`. + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - - `:mcp` + 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: Array[:direct | :programmatic]` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - The tool invocation context(s). + 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. - - `:direct` + - `:"gpt-5.6-sol"` - - `:programmatic` + - `:"gpt-5.6-terra"` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `:"gpt-5.6-luna"` - List of allowed tool names or a filter object. + - `:"gpt-5.4"` - - `McpAllowedTools = Array[String]` + - `:"gpt-5.4-mini"` - A string array of allowed tool names + - `:"gpt-5.4-nano"` - - `class McpToolFilter` + - `:"gpt-5.4-mini-2026-03-17"` - A filter object to specify which tools are allowed. + - `:"gpt-5.4-nano-2026-03-17"` - - `read_only: bool` + - `:"gpt-5.3-chat-latest"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `:"gpt-5.2"` - - `tool_names: Array[String]` + - `:"gpt-5.2-2025-12-11"` - List of allowed tool names. + - `:"gpt-5.2-chat-latest"` - - `authorization: String` + - `:"gpt-5.2-pro"` - 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.2-pro-2025-12-11"` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:"gpt-5.1"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `:"gpt-5.1-2025-11-13"` - Currently supported `connector_id` values are: + - `:"gpt-5.1-codex"` - - 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.1-mini"` - - `:connector_dropbox` + - `:"gpt-5.1-chat-latest"` - - `:connector_gmail` + - `:"gpt-5"` - - `:connector_googlecalendar` + - `:"gpt-5-mini"` - - `:connector_googledrive` + - `:"gpt-5-nano"` - - `:connector_microsoftteams` + - `:"gpt-5-2025-08-07"` - - `:connector_outlookcalendar` + - `:"gpt-5-mini-2025-08-07"` - - `:connector_outlookemail` + - `:"gpt-5-nano-2025-08-07"` - - `:connector_sharepoint` + - `:"gpt-5-chat-latest"` - - `defer_loading: bool` + - `:"gpt-4.1"` - Whether this MCP tool is deferred and discovered via tool search. + - `:"gpt-4.1-mini"` - - `headers: Hash[Symbol, String]` + - `:"gpt-4.1-nano"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `:"gpt-4.1-2025-04-14"` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:"gpt-4.1-mini-2025-04-14"` - Specify which of the MCP server's tools require approval. + - `:"gpt-4.1-nano-2025-04-14"` - - `class McpToolApprovalFilter` + - `:"o4-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. + - `:"o4-mini-2025-04-16"` - - `always: Always{ read_only, tool_names}` + - `:o3` - A filter object to specify which tools are allowed. + - `:"o3-2025-04-16"` - - `read_only: bool` + - `:"o3-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. + - `:"o3-mini-2025-01-31"` - - `tool_names: Array[String]` + - `:o1` - List of allowed tool names. + - `:"o1-2024-12-17"` - - `never: Never{ read_only, tool_names}` + - `:"o1-preview"` - A filter object to specify which tools are allowed. + - `:"o1-preview-2024-09-12"` - - `read_only: bool` + - `:"o1-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. + - `:"o1-mini-2024-09-12"` - - `tool_names: Array[String]` + - `:"gpt-4o"` - List of allowed tool names. + - `:"gpt-4o-2024-11-20"` - - `McpToolApprovalSetting = :always | :never` + - `:"gpt-4o-2024-08-06"` - 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-2024-05-13"` - - `:always` + - `:"gpt-4o-audio-preview"` - - `:never` + - `:"gpt-4o-audio-preview-2024-10-01"` - - `server_description: String` + - `:"gpt-4o-audio-preview-2024-12-17"` - Optional description of the MCP server, used to provide more context. + - `:"gpt-4o-audio-preview-2025-06-03"` - - `server_url: String` + - `:"gpt-4o-mini-audio-preview"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - - `tunnel_id: String` + - `:"gpt-4o-search-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. + - `:"gpt-4o-mini-search-preview"` - - `class CodeInterpreter` + - `:"gpt-4o-search-preview-2025-03-11"` - A tool that runs Python code to help generate a response to a prompt. + - `:"gpt-4o-mini-search-preview-2025-03-11"` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `:"chatgpt-4o-latest"` - 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. + - `:"codex-mini-latest"` - - `String = String` + - `:"gpt-4o-mini"` - The container ID. + - `:"gpt-4o-mini-2024-07-18"` - - `class CodeInterpreterToolAuto` + - `:"gpt-4-turbo"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `:"gpt-4-turbo-2024-04-09"` - - `type: :auto` + - `:"gpt-4-0125-preview"` - Always `auto`. + - `:"gpt-4-turbo-preview"` - - `:auto` + - `:"gpt-4-1106-preview"` - - `file_ids: Array[String]` + - `:"gpt-4-vision-preview"` - An optional list of uploaded files to make available to your code. + - `:"gpt-4"` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:"gpt-4-0314"` - The memory limit for the code interpreter container. + - `:"gpt-4-0613"` - - `:"1g"` + - `:"gpt-4-32k"` - - `:"4g"` + - `:"gpt-4-32k-0314"` - - `:"16g"` + - `:"gpt-4-32k-0613"` - - `:"64g"` + - `:"gpt-3.5-turbo"` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:"gpt-3.5-turbo-16k"` - Network access policy for the container. + - `:"gpt-3.5-turbo-0301"` - - `class BetaContainerNetworkPolicyDisabled` + - `:"gpt-3.5-turbo-0613"` - - `type: :disabled` + - `:"gpt-3.5-turbo-1106"` - Disable outbound network access. Always `disabled`. + - `:"gpt-3.5-turbo-0125"` - - `:disabled` + - `:"gpt-3.5-turbo-16k-0613"` - - `class BetaContainerNetworkPolicyAllowlist` + - `:"o1-pro"` - - `allowed_domains: Array[String]` + - `:"o1-pro-2025-03-19"` - A list of allowed domains when type is `allowlist`. + - `:"o3-pro"` - - `type: :allowlist` + - `:"o3-pro-2025-06-10"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `:"o3-deep-research"` - - `:allowlist` + - `:"o3-deep-research-2025-06-26"` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `:"o4-mini-deep-research"` - Optional domain-scoped secrets for allowlisted domains. + - `:"o4-mini-deep-research-2025-06-26"` - - `domain: String` + - `:"computer-use-preview"` - The domain associated with the secret. + - `:"computer-use-preview-2025-03-11"` - - `name: String` + - `:"gpt-5-codex"` - The name of the secret to inject for the domain. + - `:"gpt-5-pro"` - - `value: String` + - `:"gpt-5-pro-2025-10-06"` - The secret value to inject for the domain. + - `:"gpt-5.1-codex-max"` - - `type: :code_interpreter` + - `String = String` - The type of the code interpreter tool. Always `code_interpreter`. + - `object: :response` - - `:code_interpreter` + The object type of this resource - always set to `response`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:response` - The tool invocation context(s). + - `output: Array[BetaResponseOutputItem]` - - `:direct` + An array of content items generated by the model. - - `:programmatic` + - 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. - - `class ProgrammaticToolCalling` + - `class BetaResponseOutputMessage` - - `type: :programmatic_tool_calling` + An output message from the model. - The type of the tool. Always `programmatic_tool_calling`. + - `class BetaResponseFileSearchToolCall` - - `:programmatic_tool_calling` + 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. - - `class ImageGeneration` + - `class BetaResponseFunctionToolCall` - A tool that generates images using the GPT image models. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `type: :image_generation` + - `class BetaResponseFunctionToolCallOutputItem` - The type of the image generation tool. Always `image_generation`. + - `id: String` - - `:image_generation` + The unique ID of the function call tool output. - - `action: :generate | :edit | :auto` + - `call_id: String` - Whether to generate a new image or edit an existing image. Default: `auto`. + The unique ID of the function tool call generated by the model. - - `:generate` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:edit` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `:auto` + - `String = String` - - `background: :transparent | :opaque | :auto` + A string of the output of the function call. - 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. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - `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. + Text, image, or file output of the function call. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class BetaResponseInputText` - - `:transparent` + A text input to the model. - - `:opaque` + - `class BetaResponseInputImage` - - `:auto` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `input_fidelity: :high | :low` + - `class BetaResponseInputFile` - 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` + - `status: :in_progress | :completed | :incomplete` - - `:low` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `:in_progress` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `:completed` - - `file_id: String` + - `:incomplete` - File ID for the mask image. + - `type: :function_call_output` - - `image_url: String` + The type of the function tool call output. Always `function_call_output`. - Base64-encoded mask image. + - `:function_call_output` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `agent: Agent{ agent_name}` - The image generation model to use. Default: `gpt-image-1`. + The agent that produced this item. - - `String = String` + - `agent_name: String` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The canonical name of the agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:"gpt-image-1"` + The execution context that produced this tool call. - - `:"gpt-image-1-mini"` + - `class Direct` - - `:"gpt-image-2"` + - `type: :direct` - - `:"gpt-image-2-2026-04-21"` + The caller type. Always `direct`. - - `:"gpt-image-1.5"` + - `:direct` - - `:"chatgpt-image-latest"` + - `class Program` - - `moderation: :auto | :low` + - `caller_id: String` - Moderation level for the generated image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `:auto` + - `type: :program` - - `:low` + The caller type. Always `program`. - - `output_compression: Integer` + - `:program` - Compression level for the output image. Default: 100. + - `created_by: String` - - `output_format: :png | :webp | :jpeg` + The identifier of the actor that created the item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `class AgentMessage` - - `:png` + - `id: String` - - `:webp` + The unique ID of the agent message. - - `:jpeg` + - `author: String` - - `partial_images: Integer` + The sending agent identity. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `quality: :low | :medium | :high | :auto` + Encrypted content sent between agents. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `class BetaResponseInputText` - - `:low` + A text input to the model. - - `:medium` + - `class BetaResponseOutputText` - - `:high` + A text output from the model. - - `:auto` + - `class Text` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + A text content. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `text: String` - - `String = String` + - `type: :text` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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`. + - `class SummaryText` - - `:"1024x1024"` + A summary text from the model. - - `:"1024x1536"` + - `text: String` - - `:"1536x1024"` + A summary of the reasoning output from the model so far. - - `:auto` + - `type: :summary_text` - - `class LocalShell` + The type of the object. Always `summary_text`. - A tool that allows the model to execute shell commands in a local environment. + - `:summary_text` - - `type: :local_shell` + - `class ReasoningText` - The type of the local shell tool. Always `local_shell`. + Reasoning text from the model. - - `:local_shell` + - `text: String` - - `class BetaFunctionShellTool` + The reasoning text from the model. - A tool that allows the model to execute shell commands. + - `type: :reasoning_text` - - `type: :shell` + The type of the reasoning text. Always `reasoning_text`. - The type of the shell tool. Always `shell`. + - `:reasoning_text` - - `:shell` + - `class BetaResponseOutputRefusal` - - `allowed_callers: Array[:direct | :programmatic]` + A refusal from the model. - The tool invocation context(s). + - `class BetaResponseInputImage` - - `:direct` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:programmatic` + - `class ComputerScreenshot` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + A screenshot of a computer. - - `class BetaContainerAuto` + - `detail: :low | :high | :auto | :original` - - `type: :container_auto` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Automatically creates a container for this request + - `:low` - - `:container_auto` + - `:high` - - `file_ids: Array[String]` + - `:auto` - An optional list of uploaded files to make available to your code. + - `:original` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `file_id: String` - The memory limit for the container. + The identifier of an uploaded file that contains the screenshot. - - `:"1g"` + - `image_url: String` - - `:"4g"` + The URL of the screenshot image. - - `:"16g"` + - `type: :computer_screenshot` - - `:"64g"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:computer_screenshot` - Network access policy for the container. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class BetaContainerNetworkPolicyDisabled` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaContainerNetworkPolicyAllowlist` + - `mode: :explicit` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + The breakpoint mode. Always `explicit`. - An optional list of skills referenced by id or inline data. + - `:explicit` - - `class BetaSkillReference` + - `class BetaResponseInputFile` - - `skill_id: String` + A file input to the model. - The ID of the referenced skill. + - `class EncryptedContent` - - `type: :skill_reference` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - References a skill created with the /v1/skills endpoint. + - `encrypted_content: String` - - `:skill_reference` + Opaque encrypted content. - - `version: String` + - `type: :encrypted_content` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of the input item. Always `encrypted_content`. - - `class BetaInlineSkill` + - `:encrypted_content` - - `description: String` + - `recipient: String` - The description of the skill. + The destination agent identity. - - `name: String` + - `type: :agent_message` - The name of the skill. + The type of the item. Always `agent_message`. - - `source: BetaInlineSkillSource` + - `:agent_message` - Inline skill payload + - `agent: Agent{ 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`. + - `class MultiAgentCall` - - `:"application/zip"` + - `id: String` - - `type: :base64` + The unique ID of the multi-agent call item. - The type of the inline skill source. Must be `base64`. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:base64` + The multi-agent action to execute. - - `type: :inline` + - `:spawn_agent` - Defines an inline skill for this request. + - `:interrupt_agent` - - `:inline` + - `:list_agents` - - `class BetaLocalEnvironment` + - `:send_message` - - `type: :local` + - `:followup_task` - Use a local computer environment. + - `:wait_agent` - - `:local` + - `arguments: String` - - `skills: Array[BetaLocalSkill]` + The JSON string of arguments generated for the action. - An optional list of skills. + - `call_id: String` - - `description: String` + The unique ID linking this call to its output. - The description of the skill. + - `type: :multi_agent_call` - - `name: String` + The type of the multi-agent call. Always `multi_agent_call`. - The name of the skill. + - `:multi_agent_call` - - `path: String` + - `agent: Agent{ agent_name}` - The path to the directory containing the skill. + The agent that produced this item. - - `class BetaContainerReference` + - `agent_name: String` - - `container_id: String` + The canonical name of the agent that produced this item. - The ID of the referenced container. + - `class MultiAgentCallOutput` - - `type: :container_reference` + - `id: String` - References a container created with the /v1/containers endpoint + The unique ID of the multi-agent call output item. - - `:container_reference` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `class BetaCustomTool` + The multi-agent action that produced this result. - 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) + - `:spawn_agent` - - `name: String` + - `:interrupt_agent` - The name of the custom tool, used to identify it in tool calls. + - `:list_agents` - - `type: :custom` + - `:send_message` - The type of the custom tool. Always `custom`. + - `:followup_task` - - `:custom` + - `:wait_agent` - - `allowed_callers: Array[:direct | :programmatic]` + - `call_id: String` - The tool invocation context(s). + The unique ID of the multi-agent call. - - `:direct` + - `output: Array[BetaResponseOutputText]` - - `:programmatic` + Text output returned by the multi-agent action. - - `defer_loading: bool` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - Whether this tool should be deferred and discovered via tool search. + The annotations of the text output. - - `description: String` + - `text: String` - Optional description of the custom tool, used to provide more context. + The text output from the model. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `type: :output_text` - The input format for the custom tool. Default is unconstrained text. + The type of the output text. Always `output_text`. - - `class Text` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - Unconstrained free-form text. + - `type: :multi_agent_call_output` - - `type: :text` + The type of the multi-agent result. Always `multi_agent_call_output`. - Unconstrained text format. Always `text`. + - `:multi_agent_call_output` - - `:text` + - `agent: Agent{ agent_name}` - - `class Grammar` + 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. + - `class BetaResponseFunctionWebSearch` - - `syntax: :lark | :regex` + 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 syntax of the grammar definition. One of `lark` or `regex`. + - `class BetaResponseComputerToolCall` - - `: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` + - `class BetaResponseComputerToolCallOutputItem` - - `type: :grammar` + - `id: String` - Grammar format. Always `grammar`. + The unique ID of the computer call tool output. - - `:grammar` + - `call_id: String` - - `class BetaNamespaceTool` + 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 | :incomplete | :failed | :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[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `:incomplete` - The function/custom tools available inside this namespace. + - `:failed` - - `class Function` + - `: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: Array[:direct | :programmatic]` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ 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: bool` + - `code: String` - Whether this function should be deferred and discovered via tool search. + The type of the pending safety check. - - `description: String` + - `message: String` - - `output_schema: Hash[Symbol, untyped]` + 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: Agent{ agent_name}` - - `parameters: untyped` + The agent that produced this item. - - `strict: bool` + - `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. - - `class BetaCustomTool` + - `created_by: 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 identifier of the actor that created the item. - - `type: :namespace` + - `class BetaResponseReasoningItem` - The type of the tool. Always `namespace`. + 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). - - `:namespace` + - `class Program` - - `class BetaToolSearchTool` + - `id: String` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the program item. - - `type: :tool_search` + - `call_id: String` - The type of the tool. Always `tool_search`. + The stable call ID of the program item. - - `:tool_search` + - `code: String` - - `description: String` + The JavaScript source executed by programmatic tool calling. - Description shown to the model for a client-executed tool search tool. + - `fingerprint: String` - - `execution: :server | :client` + Opaque program replay fingerprint that must be round-tripped. - Whether tool search is executed by the server or by the client. + - `type: :program` - - `:server` + The type of the item. Always `program`. - - `:client` + - `:program` - - `parameters: untyped` + - `agent: Agent{ agent_name}` - Parameter schema for a client-executed tool search tool. + The agent that produced this item. - - `class BetaWebSearchPreviewTool` + - `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 | :web_search_preview_2025_03_11` + - `class ProgramOutput` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `id: String` - - `:web_search_preview` + The unique ID of the program output item. - - `:web_search_preview_2025_03_11` + - `call_id: String` - - `search_content_types: Array[:text | :image]` + The call ID of the program item. - - `:text` + - `result: String` - - `:image` + The result produced by the program item. - - `search_context_size: :low | :medium | :high` + - `status: :completed | :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 item. - - `:low` + - `:completed` - - `:medium` + - `:incomplete` - - `:high` + - `type: :program_output` - - `user_location: UserLocation{ type, city, country, 2 more}` + The type of the item. Always `program_output`. - The user's location. + - `:program_output` - - `type: :approximate` + - `agent: Agent{ agent_name}` - The type of location approximation. Always `approximate`. + The agent that produced this item. - - `:approximate` + - `agent_name: String` - - `city: String` + The canonical name of the agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `class BetaResponseToolSearchCall` - - `country: String` + - `id: 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 tool search call item. - - `region: String` + - `arguments: untyped` - Free text input for the region of the user, e.g. `California`. + Arguments used for the tool search call. - - `timezone: 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 tool search call generated by the model. - - `class BetaApplyPatchTool` + - `execution: :server | :client` - Allows the assistant to create, delete, or update files using unified diffs. + Whether tool search was executed by the server or by the client. - - `type: :apply_patch` + - `:server` - The type of the tool. Always `apply_patch`. + - `:client` - - `:apply_patch` + - `status: :in_progress | :completed | :incomplete` - - `allowed_callers: Array[:direct | :programmatic]` + The status of the tool search call item that was recorded. - The tool invocation context(s). + - `:in_progress` - - `:direct` + - `:completed` - - `:programmatic` + - `:incomplete` - - `type: :tool_search_output` + - `type: :tool_search_call` - The type of the item. Always `tool_search_output`. + The type of the item. Always `tool_search_call`. - - `:tool_search_output` + - `:tool_search_call` - `agent: Agent{ agent_name}` @@ -104461,35 +115790,37 @@ puts(beta_compacted_response) The identifier of the actor that created the item. - - `class AdditionalTools` + - `class BetaResponseToolSearchOutputItem` - `id: String` - The unique ID of the additional tools item. + The unique ID of the tool search output item. - - `role: :unknown | :user | :assistant | 5 more` + - `call_id: String` - The role that provided the additional tools. + The unique ID of the tool search call generated by the model. - - `:unknown` + - `execution: :server | :client` - - `:user` + Whether tool search was executed by the server or by the client. - - `:assistant` + - `:server` - - `:system` + - `:client` + + - `status: :in_progress | :completed | :incomplete` - - `:critic` + The status of the tool search output item that was recorded. - - `:discriminator` + - `:in_progress` - - `:developer` + - `:completed` - - `:tool` + - `:incomplete` - `tools: Array[BetaTool]` - The additional tool definitions made available at this item. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool` @@ -104555,11 +115886,11 @@ puts(beta_compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: :additional_tools` + - `type: :tool_search_output` - The type of the item. Always `additional_tools`. + The type of the item. Always `tool_search_output`. - - `:additional_tools` + - `:tool_search_output` - `agent: Agent{ agent_name}` @@ -104569,134 +115900,109 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem` - - 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[Summary{ 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` + - `created_by: String` - The type of the object. Always `reasoning`. + The identifier of the actor that created the item. - - `:reasoning` + - `class AdditionalTools` - - `agent: Agent{ agent_name}` + - `id: String` - The agent that produced this item. + The unique ID of the additional tools item. - - `agent_name: String` + - `role: :unknown | :user | :assistant | 5 more` - The canonical name of the agent that produced this item. + The role that provided the additional tools. - - `content: Array[Content{ text, type}]` + - `:unknown` - Reasoning text content. + - `:user` - - `text: String` + - `:assistant` - The reasoning text from the model. + - `:system` - - `type: :reasoning_text` + - `:critic` - The type of the reasoning text. Always `reasoning_text`. + - `:discriminator` - - `:reasoning_text` + - `:developer` - - `encrypted_content: String` + - `:tool` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `tools: Array[BetaTool]` - - `status: :in_progress | :completed | :incomplete` + The additional tool definitions made available at this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaFunctionTool` - - `: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` + - `class BetaFileSearchTool` - - `: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). - - `class Program` + - `class BetaComputerTool` - - `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 program item. + - `class BetaComputerUsePreviewTool` - - `call_id: String` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The stable call ID of the program item. + - `class BetaWebSearchTool` - - `code: 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 JavaScript source executed by programmatic tool calling. + - `class Mcp` - - `fingerprint: 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). - Opaque program replay fingerprint that must be round-tripped. + - `class CodeInterpreter` - - `type: :program` + A tool that runs Python code to help generate a response to a prompt. - The type of the item. Always `program`. + - `class ProgrammaticToolCalling` - - `:program` + - `class ImageGeneration` - - `agent: Agent{ agent_name}` + A tool that generates images using the GPT image models. - The agent that produced this item. + - `class LocalShell` - - `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. + - `class BetaFunctionShellTool` - - `class ProgramOutput` + A tool that allows the model to execute shell commands. - - `id: String` + - `class BetaCustomTool` - The unique ID of the program output 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) - - `call_id: String` + - `class BetaNamespaceTool` - The call ID of the program item. + Groups function/custom tools under a shared namespace. - - `result: String` + - `class BetaToolSearchTool` - The result produced by the program item. + Hosted or BYOT tool search configuration for deferred tools. - - `status: :completed | :incomplete` + - `class BetaWebSearchPreviewTool` - The terminal status of the program output item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `:completed` + - `class BetaApplyPatchTool` - - `:incomplete` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: :program_output` + - `type: :additional_tools` - The type of the item. Always `program_output`. + The type of the item. Always `additional_tools`. - - `:program_output` + - `:additional_tools` - `agent: Agent{ agent_name}` @@ -104778,79 +116084,6 @@ puts(beta_compacted_response) 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[Logs{ logs, type} | Image{ type, url}]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class Logs` - - 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` - - - `class Image` - - 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 | :completed | :incomplete | 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - `class LocalShellCall` A tool call to run a command on the local shell. @@ -105193,357 +116426,1215 @@ puts(beta_compacted_response) Create a new file with the provided diff. - - `:create_file` + - `:create_file` + + - `class DeleteFile` + + 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` + + - `class UpdateFile` + + 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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + 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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call output. + + - `output: String` + + Optional textual output returned by the apply patch tool. + + - `class McpCall` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_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. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class McpListTools` + + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + 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: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: String` + + The unique ID of the custom tool call output item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: bool` + + Whether to allow the model to run tool calls in parallel. + + - `temperature: Float` + + 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 | BetaToolChoiceAllowed | BetaToolChoiceTypes | 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 | :auto | :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` + + - `class BetaToolChoiceAllowed` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: :auto | :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[Hash[Symbol, untyped]]` + + 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` + + - `class BetaToolChoiceTypes` + + 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 | :web_search_preview | :computer | 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` + + - `class BetaToolChoiceFunction` + + 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` + + - `class BetaToolChoiceMcp` + + 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: String` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom` + + 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` + + - `class BetaSpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + + - `class BetaToolChoiceApplyPatch` + + 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` + + - `class BetaToolChoiceShell` + + 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[BetaTool]` + + 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. + + - `class BetaFunctionTool` + + 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). + + - `class BetaFileSearchTool` + + 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). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + 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). + + - `class Mcp` + + 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). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + 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) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + 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). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_p: Float` + + 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: bool` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: Float` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: Conversation{ 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: Integer` + + 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: Integer` + + 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: Moderation{ input, output}` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + + Moderation for the response input. + + - `class ModerationResult` + + A moderation result produced for the response input or output. + + - `categories: Hash[Symbol, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + + Which modalities of input are reflected by the score for each category. + + - `:text` + + - `:image` + + - `category_scores: Hash[Symbol, Float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + 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` + + - `class Error` + + 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: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + + Moderation for the response output. + + - `class ModerationResult` + + A moderation result produced for the response input or output. + + - `categories: Hash[Symbol, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + + Which modalities of input are reflected by the score for each category. + + - `:text` + + - `:image` + + - `category_scores: Hash[Symbol, Float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + 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` + + - `class Error` + + 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: 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: 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: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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 = String` + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `version: String` + + Optional version of the prompt template. + + - `prompt_cache_key: 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). - - `class DeleteFile` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - Instruction describing how to delete a file via the apply_patch tool. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `path: String` + - `mode: :implicit | :explicit` - Path of the file to delete. + Whether implicit prompt-cache breakpoints were enabled. - - `type: :delete_file` + - `:implicit` - Delete the specified file. + - `:explicit` - - `:delete_file` + - `ttl: :"30m"` - - `class UpdateFile` + The minimum lifetime applied to each cache breakpoint. - Instruction describing how to update a file via the apply_patch tool. + - `:"30m"` - - `diff: String` + - `prompt_cache_retention: :in_memory | :"24h"` - Diff to apply. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `path: 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. - Path of the file to update. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: :update_file` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Update an existing file with the provided diff. + - `:in_memory` - - `:update_file` + - `:"24h"` - - `status: :in_progress | :completed` + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - The status of the apply patch tool call. One of `in_progress` or `completed`. + **gpt-5 and o-series models only** - - `:in_progress` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `:completed` + - `context: :auto | :current_turn | :all_turns` - - `type: :apply_patch_call` + 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 type of the item. Always `apply_patch_call`. + - `:auto` - - `:apply_patch_call` + - `:current_turn` - - `agent: Agent{ agent_name}` + - `:all_turns` - The agent that produced this item. + - `effort: :none | :minimal | :low | 4 more` - - `agent_name: 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 canonical name of the agent that produced this item. + - `:none` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:minimal` - The execution context that produced this tool call. + - `:low` - - `class Direct` + - `:medium` - - `type: :direct` + - `:high` - - `:direct` + - `:xhigh` - - `class Program` + - `:max` - - `caller_id: String` + - `generate_summary: :auto | :concise | :detailed` - The call ID of the program item that produced this tool call. + **Deprecated:** use `summary` instead. - - `type: :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`. - - `:program` + - `:auto` - - `created_by: String` + - `:concise` - The ID of the entity that created this tool call. + - `:detailed` - - `class BetaResponseApplyPatchToolCallOutput` + - `mode: String | :standard | :pro` - The output emitted by an apply patch tool call. + 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 apply patch tool call output. Populated when this item is returned via API. + - `String = String` - - `call_id: String` + - `Mode = :standard | :pro` - The unique ID of the apply patch tool call generated by the model. + Controls the reasoning execution mode for the request. - - `status: :completed | :failed` + When returned on a response, this is the effective execution mode. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `:standard` - - `:completed` + - `:pro` - - `:failed` + - `summary: :auto | :concise | :detailed` - - `type: :apply_patch_call_output` + 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 `apply_patch_call_output`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `:apply_patch_call_output` + - `:auto` - - `agent: Agent{ agent_name}` + - `:concise` - The agent that produced this item. + - `:detailed` - - `agent_name: String` + - `safety_identifier: String` - The canonical name of the agent that produced this item. + 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). - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `service_tier: :auto | :default | :flex | 2 more` - The execution context that produced this tool call. + Specifies the processing type used for serving the request. - - `class 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'. - - `type: :direct` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `:direct` + - `:auto` - - `class Program` + - `:default` - - `caller_id: String` + - `:flex` - The call ID of the program item that produced this tool call. + - `:scale` - - `type: :program` + - `:priority` - - `:program` + - `status: BetaResponseStatus` - - `created_by: String` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The ID of the entity that created this tool call output. + - `:completed` - - `output: String` + - `:failed` - Optional textual output returned by the apply patch tool. + - `:in_progress` - - `class McpListTools` + - `:cancelled` - A list of tools available on an MCP server. + - `:queued` - - `id: String` + - `:incomplete` - The unique ID of the list. + - `text: BetaResponseTextConfig` - - `server_label: String` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The label of the MCP server. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `format_: BetaResponseFormatTextConfig` - The tools available on the server. + An object specifying the format that the model must output. - - `input_schema: untyped` + 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 JSON schema describing the tool's input. + The default format is `{ "type": "text" }` with no additional options. - - `name: String` + **Not recommended for gpt-4o and newer models:** - The name of the tool. + 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. - - `annotations: untyped` + - `class Text` - Additional annotations about the tool. + Default response format. Used to generate text responses. - - `description: String` + - `type: :text` - The description of the tool. + The type of response format being defined. Always `text`. - - `type: :mcp_list_tools` + - `:text` - The type of the item. Always `mcp_list_tools`. + - `class BetaResponseFormatTextJSONSchemaConfig` - - `:mcp_list_tools` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `agent: Agent{ 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: Hash[Symbol, untyped]` - 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/). - - `error: String` + - `type: :json_schema` - Error message if the server could not list tools. + The type of response format being defined. Always `json_schema`. - - `class McpApprovalRequest` + - `:json_schema` - A request for human approval of a tool invocation. + - `description: String` - - `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 approval request. + - `strict: bool` - - `arguments: 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). - A JSON string of arguments for the tool. + - `class JSONObject` - - `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 tool to run. + - `type: :json_object` - - `server_label: String` + The type of response format being defined. Always `json_object`. - The label of the MCP server making the request. + - `:json_object` - - `type: :mcp_approval_request` + - `verbosity: :low | :medium | :high` - The type of the item. Always `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`. - - `:mcp_approval_request` + - `:low` - - `agent: Agent{ agent_name}` + - `:medium` - The agent that produced this item. + - `:high` - - `agent_name: String` + - `top_logprobs: Integer` - The canonical name of the agent that produced this item. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `class McpApprovalResponse` + - `truncation: :auto | :disabled` - A response to an MCP approval request. + The truncation strategy to use for the model response. - - `id: 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 unique ID of the approval response + - `:auto` - - `approval_request_id: String` + - `:disabled` - The ID of the approval request being answered. + - `usage: BetaResponseUsage` - - `approve: bool` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Whether the request was approved. + - `input_tokens: Integer` - - `type: :mcp_approval_response` + The number of input tokens. - The type of the item. Always `mcp_approval_response`. + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - - `:mcp_approval_response` + A detailed breakdown of the input tokens. - - `agent: Agent{ agent_name}` + - `cache_write_tokens: Integer` - The agent that produced this item. + The number of input tokens that were written to the cache. - - `agent_name: String` + - `cached_tokens: Integer` - The canonical name of the agent that produced this item. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `reason: String` + - `output_tokens: Integer` - Optional reason for the decision. + The number of output tokens. - - `class McpCall` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - An invocation of a tool on an MCP server. + A detailed breakdown of the output tokens. - - `id: String` + - `reasoning_tokens: Integer` - The unique ID of the tool call. + The number of reasoning tokens. - - `arguments: String` + - `total_tokens: Integer` - A JSON string of the arguments passed to the tool. + The total number of tokens used. - - `name: String` + - `user: String` - The name of the tool that was run. + 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). - - `server_label: String` + - `sequence_number: Integer` - The label of the MCP server running the tool. + The sequence number for this event. - - `type: :mcp_call` + - `type: :"response.queued"` - The type of the item. Always `mcp_call`. + The type of the event. Always 'response.queued'. - - `:mcp_call` + - `:"response.queued"` - `agent: Agent{ 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: String` +### Beta Response Reasoning Item - 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. +- `class BetaResponseReasoningItem` - - `error: 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). - The error from the tool call, if any. + - `id: String` - - `output: String` + The unique identifier of the reasoning content. - The output from the tool call. + - `summary: Array[Summary{ text, type}]` - - `status: :in_progress | :completed | :incomplete | 2 more` + Reasoning summary content. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `text: String` - - `:in_progress` + A summary of the reasoning output from the model so far. - - `:completed` + - `type: :summary_text` - - `:incomplete` + The type of the object. Always `summary_text`. - - `:calling` + - `:summary_text` - - `:failed` + - `type: :reasoning` - - `class BetaResponseCustomToolCallItem` + The type of the object. Always `reasoning`. - A call to a custom tool created by the model. + - `:reasoning` - - `id: String` + - `agent: Agent{ agent_name}` - The unique ID of the custom tool call item. + The agent that produced this item. - - `status: :in_progress | :completed | :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` + - `content: Array[Content{ text, type}]` - - `:completed` + Reasoning text content. - - `:incomplete` + - `text: String` - - `created_by: String` + The reasoning text from the model. - The identifier of the actor that created the item. + - `type: :reasoning_text` - - `class BetaResponseCustomToolCallOutputItem` + The type of the reasoning text. Always `reasoning_text`. - The output of a custom tool call from your code, being sent back to the model. + - `:reasoning_text` - - `id: String` + - `encrypted_content: String` - The unique ID of the custom tool call output item. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: :in_progress | :completed | :incomplete` @@ -105556,49 +117647,47 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` - - The identifier of the actor that created the item. - -### Beta Response Local Environment - -- `class BetaResponseLocalEnvironment` +### Beta Response Reasoning Summary Part Added Event - Represents the use of a local environment to perform shell actions. +- `class BetaResponseReasoningSummaryPartAddedEvent` - - `type: :local` + Emitted when a new reasoning summary part is added. - The environment type. Always `local`. + - `item_id: String` - - `:local` + The ID of the item this summary part is associated with. -### Beta Response Mcp Call Arguments Delta Event + - `output_index: Integer` -- `class BetaResponseMcpCallArgumentsDeltaEvent` + The index of the output item this summary part is associated with. - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `part: Part{ text, type}` - - `delta: String` + The summary part that was added. - A JSON string containing the partial update to the arguments for the MCP tool call. + - `text: String` - - `item_id: String` + The text of the summary part. - The unique identifier of the MCP tool call item being processed. + - `type: :summary_text` - - `output_index: Integer` + The type of the summary part. Always `summary_text`. - The index of the output item in the response's output array. + - `:summary_text` - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_call_arguments.delta"` + - `summary_index: Integer` - The type of the event. Always 'response.mcp_call_arguments.delta'. + The index of the summary part within the reasoning summary. - - `:"response.mcp_call_arguments.delta"` + - `type: :"response.reasoning_summary_part.added"` + + The type of the event. Always `response.reasoning_summary_part.added`. + + - `:"response.reasoning_summary_part.added"` - `agent: Agent{ agent_name}` @@ -105608,33 +117697,47 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call Arguments Done Event - -- `class BetaResponseMcpCallArgumentsDoneEvent` - - Emitted when the arguments for an MCP tool call are finalized. +### Beta Response Reasoning Summary Part Done Event - - `arguments: String` +- `class BetaResponseReasoningSummaryPartDoneEvent` - A JSON string containing the finalized arguments for the MCP tool call. + Emitted when a reasoning summary part is completed. - `item_id: String` - The unique identifier of the MCP tool call item being processed. + The ID of the item this summary part is associated with. - `output_index: Integer` - The index of the output item in the response's output array. + The index of the output item this summary part is associated with. + + - `part: Part{ 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: Integer` The sequence number of this event. - - `type: :"response.mcp_call_arguments.done"` + - `summary_index: Integer` - The type of the event. Always 'response.mcp_call_arguments.done'. + The index of the summary part within the reasoning summary. - - `:"response.mcp_call_arguments.done"` + - `type: :"response.reasoning_summary_part.done"` + + The type of the event. Always `response.reasoning_summary_part.done`. + + - `:"response.reasoning_summary_part.done"` - `agent: Agent{ agent_name}` @@ -105644,29 +117747,44 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call Completed Event + - `status: :incomplete` -- `class BetaResponseMcpCallCompletedEvent` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - Emitted when an MCP tool call has completed successfully. + - `:incomplete` + +### Beta Response Reasoning Summary Text Delta Event + +- `class BetaResponseReasoningSummaryTextDeltaEvent` + + Emitted when a delta is added to a reasoning summary text. + + - `delta: String` + + The text delta that was added to the summary. - `item_id: String` - The ID of the MCP tool call item that completed. + The ID of the item this summary text delta is associated with. - `output_index: Integer` - The index of the output item that completed. + The index of the output item this summary text delta is associated with. - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_call.completed"` + - `summary_index: Integer` - The type of the event. Always 'response.mcp_call.completed'. + The index of the summary part within the reasoning summary. - - `:"response.mcp_call.completed"` + - `type: :"response.reasoning_summary_text.delta"` + + The type of the event. Always `response.reasoning_summary_text.delta`. + + - `:"response.reasoning_summary_text.delta"` - `agent: Agent{ agent_name}` @@ -105676,29 +117794,37 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call Failed Event +### Beta Response Reasoning Summary Text Done Event -- `class BetaResponseMcpCallFailedEvent` +- `class BetaResponseReasoningSummaryTextDoneEvent` - Emitted when an MCP tool call has failed. + Emitted when a reasoning summary text is completed. - `item_id: String` - The ID of the MCP tool call item that failed. + The ID of the item this summary text is associated with. - `output_index: Integer` - The index of the output item that failed. + The index of the output item this summary text is associated with. - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_call.failed"` + - `summary_index: Integer` - The type of the event. Always 'response.mcp_call.failed'. + The index of the summary part within the reasoning summary. - - `:"response.mcp_call.failed"` + - `text: String` + + The full text of the completed reasoning summary. + + - `type: :"response.reasoning_summary_text.done"` + + The type of the event. Always `response.reasoning_summary_text.done`. + + - `:"response.reasoning_summary_text.done"` - `agent: Agent{ agent_name}` @@ -105708,29 +117834,37 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call In Progress Event +### Beta Response Reasoning Text Delta Event -- `class BetaResponseMcpCallInProgressEvent` +- `class BetaResponseReasoningTextDeltaEvent` - Emitted when an MCP tool call is in progress. + Emitted when a delta is added to a reasoning text. + + - `content_index: Integer` + + The index of the reasoning content part this delta is associated with. + + - `delta: String` + + The text delta that was added to the reasoning content. - `item_id: String` - The unique identifier of the MCP tool call item being processed. + The ID of the item this reasoning text delta is associated with. - `output_index: Integer` - The index of the output item in the response's output array. + The index of the output item this reasoning text delta is associated with. - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_call.in_progress"` + - `type: :"response.reasoning_text.delta"` - The type of the event. Always 'response.mcp_call.in_progress'. + The type of the event. Always `response.reasoning_text.delta`. - - `:"response.mcp_call.in_progress"` + - `:"response.reasoning_text.delta"` - `agent: Agent{ agent_name}` @@ -105740,29 +117874,37 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp List Tools Completed Event +### Beta Response Reasoning Text Done Event -- `class BetaResponseMcpListToolsCompletedEvent` +- `class BetaResponseReasoningTextDoneEvent` - Emitted when the list of available MCP tools has been successfully retrieved. + Emitted when a reasoning text is completed. + + - `content_index: Integer` + + The index of the reasoning content part. - `item_id: String` - The ID of the MCP tool call item that produced this output. + The ID of the item this reasoning text is associated with. - `output_index: Integer` - The index of the output item that was processed. + The index of the output item this reasoning text is associated with. - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_list_tools.completed"` + - `text: String` - The type of the event. Always 'response.mcp_list_tools.completed'. + The full text of the completed reasoning content. - - `:"response.mcp_list_tools.completed"` + - `type: :"response.reasoning_text.done"` + + The type of the event. Always `response.reasoning_text.done`. + + - `:"response.reasoning_text.done"` - `agent: Agent{ agent_name}` @@ -105772,29 +117914,37 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp List Tools Failed Event +### Beta Response Refusal Delta Event -- `class BetaResponseMcpListToolsFailedEvent` +- `class BetaResponseRefusalDeltaEvent` - Emitted when the attempt to list available MCP tools has failed. + Emitted when there is a partial refusal text. + + - `content_index: Integer` + + The index of the content part that the refusal text is added to. + + - `delta: String` + + The refusal text that is added. - `item_id: String` - The ID of the MCP tool call item that failed. + The ID of the output item that the refusal text is added to. - `output_index: Integer` - The index of the output item that failed. + The index of the output item that the refusal text is added to. - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_list_tools.failed"` + - `type: :"response.refusal.delta"` - The type of the event. Always 'response.mcp_list_tools.failed'. + The type of the event. Always `response.refusal.delta`. - - `:"response.mcp_list_tools.failed"` + - `:"response.refusal.delta"` - `agent: Agent{ agent_name}` @@ -105804,29 +117954,37 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp List Tools In Progress Event +### Beta Response Refusal Done Event -- `class BetaResponseMcpListToolsInProgressEvent` +- `class BetaResponseRefusalDoneEvent` - Emitted when the system is in the process of retrieving the list of available MCP tools. + Emitted when refusal text is finalized. + + - `content_index: Integer` + + The index of the content part that the refusal text is finalized. - `item_id: String` - The ID of the MCP tool call item that is being processed. + The ID of the output item that the refusal text is finalized. - `output_index: Integer` - The index of the output item that is being processed. + The index of the output item that the refusal text is finalized. + + - `refusal: String` + + The refusal text that is finalized. - `sequence_number: Integer` The sequence number of this event. - - `type: :"response.mcp_list_tools.in_progress"` + - `type: :"response.refusal.done"` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + The type of the event. Always `response.refusal.done`. - - `:"response.mcp_list_tools.in_progress"` + - `:"response.refusal.done"` - `agent: Agent{ agent_name}` @@ -105836,395 +117994,402 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Output Audio +### Beta Response Status -- `class BetaResponseOutputAudio` +- `BetaResponseStatus = :completed | :failed | :in_progress | 3 more` - An audio output from the model. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `data: String` + - `:completed` - Base64-encoded audio data from the model. + - `:failed` - - `transcript: String` + - `:in_progress` - The transcript of the audio data from the model. + - `:cancelled` - - `type: :output_audio` + - `:queued` - The type of the output audio. Always `output_audio`. + - `:incomplete` - - `:output_audio` +### Beta Response Stream Event -### Beta Response Output Item +- `BetaResponseStreamEvent = BetaResponseAudioDeltaEvent | BetaResponseAudioDoneEvent | BetaResponseAudioTranscriptDeltaEvent | 50 more` -- `BetaResponseOutputItem = BetaResponseOutputMessage | BetaResponseFileSearchToolCall | BetaResponseFunctionToolCall | 28 more` + Emitted when there is a partial audio response. - An output message from the model. + - `class BetaResponseAudioDeltaEvent` - - `class BetaResponseOutputMessage` + Emitted when there is a partial audio response. - An output message from the model. + - `delta: String` - - `id: String` + A chunk of Base64 encoded response audio bytes. - The unique ID of the output message. + - `sequence_number: Integer` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + A sequence number for this chunk of the stream response. - The content of the output message. + - `type: :"response.audio.delta"` - - `class BetaResponseOutputText` + The type of the event. Always `response.audio.delta`. - A text output from the model. + - `:"response.audio.delta"` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `agent: Agent{ agent_name}` - The annotations of the text output. + The agent that owns this multi-agent streaming event. - - `class FileCitation` + - `agent_name: String` - A citation to a file. + The canonical name of the agent that produced this item. - - `file_id: String` + - `class BetaResponseAudioDoneEvent` - The ID of the file. + Emitted when the audio response is complete. - - `filename: String` + - `sequence_number: Integer` - The filename of the file cited. + The sequence number of the delta. - - `index: Integer` + - `type: :"response.audio.done"` - The index of the file in the list of files. + The type of the event. Always `response.audio.done`. - - `type: :file_citation` + - `:"response.audio.done"` - The type of the file citation. Always `file_citation`. + - `agent: Agent{ agent_name}` - - `:file_citation` + The agent that owns this multi-agent streaming event. - - `class URLCitation` + - `agent_name: String` - A citation for a web resource used to generate a model response. + The canonical name of the agent that produced this item. - - `end_index: Integer` + - `class BetaResponseAudioTranscriptDeltaEvent` - The index of the last character of the URL citation in the message. + Emitted when there is a partial transcript of audio. - - `start_index: Integer` + - `delta: String` - The index of the first character of the URL citation in the message. + The partial transcript of the audio response. - - `title: String` + - `sequence_number: Integer` - The title of the web resource. + The sequence number of this event. - - `type: :url_citation` + - `type: :"response.audio.transcript.delta"` - The type of the URL citation. Always `url_citation`. + The type of the event. Always `response.audio.transcript.delta`. - - `:url_citation` + - `:"response.audio.transcript.delta"` - - `url: String` + - `agent: Agent{ agent_name}` - The URL of the web resource. + The agent that owns this multi-agent streaming event. - - `class ContainerFileCitation` + - `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` + - `class BetaResponseAudioTranscriptDoneEvent` - The ID of the container file. + Emitted when the full audio transcript is completed. - - `end_index: Integer` + - `sequence_number: Integer` - The index of the last character of the container file citation in the message. + The sequence number of this event. - - `file_id: String` + - `type: :"response.audio.transcript.done"` - The ID of the file. + The type of the event. Always `response.audio.transcript.done`. - - `filename: String` + - `:"response.audio.transcript.done"` - The filename of the container file cited. + - `agent: Agent{ agent_name}` - - `start_index: Integer` + The agent that owns this multi-agent streaming event. - The index of the first character of the container file citation in the message. + - `agent_name: String` - - `type: :container_file_citation` + The canonical name of the agent that produced this item. - The type of the container file citation. Always `container_file_citation`. + - `class BetaResponseCodeInterpreterCallCodeDeltaEvent` - - `:container_file_citation` + Emitted when a partial code snippet is streamed by the code interpreter. - - `class FilePath` + - `delta: String` - A path to a file. + The partial code snippet being streamed by the code interpreter. - - `file_id: String` + - `item_id: String` - The ID of the file. + The unique identifier of the code interpreter tool call item. - - `index: Integer` + - `output_index: Integer` - The index of the file in the list of files. + The index of the output item in the response for which the code is being streamed. - - `type: :file_path` + - `sequence_number: Integer` - The type of the file path. Always `file_path`. + The sequence number of this event, used to order streaming events. - - `:file_path` + - `type: :"response.code_interpreter_call_code.delta"` - - `text: String` + The type of the event. Always `response.code_interpreter_call_code.delta`. - The text output from the model. + - `:"response.code_interpreter_call_code.delta"` - - `type: :output_text` + - `agent: Agent{ agent_name}` - The type of the output text. Always `output_text`. + The agent that owns this multi-agent streaming event. - - `:output_text` + - `agent_name: String` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The canonical name of the agent that produced this item. - - `token: String` + - `class BetaResponseCodeInterpreterCallCodeDoneEvent` - - `bytes: Array[Integer]` + Emitted when the code snippet is finalized by the code interpreter. - - `logprob: Float` + - `code: String` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + The final code snippet output by the code interpreter. - - `token: String` + - `item_id: String` - - `bytes: Array[Integer]` + The unique identifier of the code interpreter tool call item. - - `logprob: Float` + - `output_index: Integer` - - `class BetaResponseOutputRefusal` + The index of the output item in the response for which the code is finalized. - A refusal from the model. + - `sequence_number: Integer` - - `refusal: String` + The sequence number of this event, used to order streaming events. - The refusal explanation from the model. + - `type: :"response.code_interpreter_call_code.done"` - - `type: :refusal` + The type of the event. Always `response.code_interpreter_call_code.done`. - The type of the refusal. Always `refusal`. + - `:"response.code_interpreter_call_code.done"` - - `:refusal` + - `agent: Agent{ agent_name}` - - `role: :assistant` + The agent that owns this multi-agent streaming event. - The role of the output message. Always `assistant`. + - `agent_name: String` - - `:assistant` + The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` + - `class BetaResponseCodeInterpreterCallCompletedEvent` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Emitted when the code interpreter call is completed. - - `:in_progress` + - `item_id: String` - - `:completed` + The unique identifier of the code interpreter tool call item. - - `:incomplete` + - `output_index: Integer` - - `type: :message` + The index of the output item in the response for which the code interpreter call is completed. - The type of the output message. Always `message`. + - `sequence_number: Integer` - - `:message` + The sequence number of this event, used to order streaming events. + + - `type: :"response.code_interpreter_call.completed"` + + The type of the event. Always `response.code_interpreter_call.completed`. + + - `:"response.code_interpreter_call.completed"` - `agent: Agent{ 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. - - `phase: :commentary` + - `class BetaResponseCodeInterpreterCallInProgressEvent` - 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. + Emitted when a code interpreter call is in progress. - - `:commentary` + - `item_id: String` - - `class BetaResponseFileSearchToolCall` + The unique identifier of the code interpreter tool call item. - 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. + - `output_index: Integer` - - `id: String` + The index of the output item in the response for which the code interpreter call is in progress. - The unique ID of the file search tool call. + - `sequence_number: Integer` - - `queries: Array[String]` + The sequence number of this event, used to order streaming events. - The queries used to search for files. + - `type: :"response.code_interpreter_call.in_progress"` - - `status: :in_progress | :searching | :completed | 2 more` + The type of the event. Always `response.code_interpreter_call.in_progress`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `:"response.code_interpreter_call.in_progress"` - - `:in_progress` + - `agent: Agent{ agent_name}` - - `:searching` + The agent that owns this multi-agent streaming event. - - `:completed` + - `agent_name: String` - - `:incomplete` + The canonical name of the agent that produced this item. - - `:failed` + - `class BetaResponseCodeInterpreterCallInterpretingEvent` - - `type: :file_search_call` + Emitted when the code interpreter is actively interpreting the code snippet. - The type of the file search tool call. Always `file_search_call`. + - `item_id: String` - - `:file_search_call` + The unique identifier of the code interpreter tool call item. - - `agent: Agent{ agent_name}` + - `output_index: Integer` - The agent that produced this item. + The index of the output item in the response for which the code interpreter is interpreting code. - - `agent_name: String` + - `sequence_number: Integer` - The canonical name of the agent that produced this item. + The sequence number of this event, used to order streaming events. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `type: :"response.code_interpreter_call.interpreting"` - The results of the file search tool call. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `attributes: Hash[Symbol, String | Float | bool]` + - `:"response.code_interpreter_call.interpreting"` - Set of 16 key-value pairs that can be attached to an object. 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. + - `agent: Agent{ agent_name}` - - `String = String` + The agent that owns this multi-agent streaming event. - - `Float = Float` + - `agent_name: String` - - `UnionMember2 = bool` + The canonical name of the agent that produced this item. - - `file_id: String` + - `class BetaResponseCompletedEvent` - The unique ID of the file. + Emitted when the model response is complete. - - `filename: String` + - `response: BetaResponse` - The name of the file. + Properties of the completed response. - - `score: Float` + - `id: String` - The relevance score of the file - a value between 0 and 1. + Unique identifier for this Response. - - `text: String` + - `created_at: Float` - The text that was retrieved from the file. + Unix timestamp (in seconds) of when this Response was created. - - `class BetaResponseFunctionToolCall` + - `error: BetaResponseError` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + An error object returned when the model fails to generate a Response. - - `arguments: String` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - A JSON string of the arguments to pass to the function. + The error code for the response. - - `call_id: String` + - `:server_error` - The unique ID of the function tool call generated by the model. + - `:rate_limit_exceeded` - - `name: String` + - `:invalid_prompt` - The name of the function to run. + - `:bio_policy` - - `type: :function_call` + - `:vector_store_timeout` - The type of the function tool call. Always `function_call`. + - `:invalid_image` - - `:function_call` + - `:invalid_image_format` - - `id: String` + - `:invalid_base64_image` - The unique ID of the function tool call. + - `:invalid_image_url` - - `agent: Agent{ 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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:invalid_image_mode` - The execution context that produced this tool call. + - `:image_file_too_large` - - `class Direct` + - `:unsupported_image_media_type` - - `type: :direct` + - `:empty_image_file` - - `:direct` + - `:failed_to_download_image` - - `class Program` + - `:image_file_not_found` - - `caller_id: String` + - `message: String` - The call ID of the program item that produced this tool call. + A human-readable description of the error. - - `type: :program` + - `incomplete_details: IncompleteDetails{ reason}` - - `:program` + Details about why the response is incomplete. - - `namespace: String` + - `reason: :max_output_tokens | :content_filter` - The namespace of the function to run. + The reason why the response is incomplete. - - `status: :in_progress | :completed | :incomplete` + - `:max_output_tokens` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:content_filter` - - `:in_progress` + - `instructions: String | Array[BetaResponseInputItem]` - - `:completed` + A system (or developer) message inserted into the model's context. - - `:incomplete` + 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. - - `class BetaResponseFunctionToolCallOutputItem` + - `String = String` - - `id: String` + A text input to the model, equivalent to a text input with the + `developer` role. - The unique ID of the function call tool output. + - `InputItemList = Array[BetaResponseInputItem]` - - `call_id: String` + A list of one or many input items to the model, containing + different content types. - The unique ID of the function tool call generated by the model. + - `class BetaEasyInputMessage` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + 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 | BetaResponseInputMessageContentList` - The output from the function call generated by your code. - Can be a string or an list of output content. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - `String = String` - A string of the output of the function call. + A text input to the model. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - Text, image, or file output of the function call. + A list of one or many input items to the model, containing different content + types. - `class BetaResponseInputText` @@ -106336,296 +118501,259 @@ puts(beta_compacted_response) - `:explicit` - - `status: :in_progress | :completed | :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 function tool call output. Always `function_call_output`. - - - `:function_call_output` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - The caller type. Always `direct`. - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - The caller type. Always `program`. + - `role: :user | :assistant | :system | :developer` - - `:program` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `created_by: String` + - `:user` - The identifier of the actor that created the item. + - `:assistant` - - `class AgentMessage` + - `:system` - - `id: String` + - `:developer` - The unique ID of the agent message. + - `phase: :commentary | :final_answer` - - `author: 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 sending agent identity. + - `:commentary` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `:final_answer` - Encrypted content sent between agents. + - `type: :message` - - `class BetaResponseInputText` + The type of the message input. Always `message`. - A text input to the model. + - `:message` - - `class BetaResponseOutputText` + - `class Message` - A text output from 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. - - `class Text` + - `content: BetaResponseInputMessageContentList` - A text content. + A list of one or many input items to the model, containing different content + types. - - `text: String` + - `role: :user | :system | :developer` - - `type: :text` + The role of the message input. One of `user`, `system`, or `developer`. - - `:text` + - `:user` - - `class SummaryText` + - `:system` - A summary text from the model. + - `:developer` - - `text: String` + - `agent: Agent{ agent_name}` - A summary of the reasoning output from the model so far. + The agent that produced this item. - - `type: :summary_text` + - `agent_name: String` - The type of the object. Always `summary_text`. + The canonical name of the agent that produced this item. - - `:summary_text` + - `status: :in_progress | :completed | :incomplete` - - `class ReasoningText` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Reasoning text from the model. + - `:in_progress` - - `text: String` + - `:completed` - The reasoning text from the model. + - `:incomplete` - - `type: :reasoning_text` + - `type: :message` - The type of the reasoning text. Always `reasoning_text`. + The type of the message input. Always set to `message`. - - `:reasoning_text` + - `:message` - - `class BetaResponseOutputRefusal` + - `class BetaResponseOutputMessage` - A refusal from the model. + An output message from the model. - - `class BetaResponseInputImage` + - `id: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the output message. - - `class ComputerScreenshot` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - A screenshot of a computer. + The content of the output message. - - `detail: :low | :high | :auto | :original` + - `class BetaResponseOutputText` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A text output from the model. - - `:low` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:high` + The annotations of the text output. - - `:auto` + - `class FileCitation` - - `:original` + A citation to a file. - `file_id: String` - The identifier of an uploaded file that contains the screenshot. + The ID of the file. - - `image_url: String` + - `filename: String` - The URL of the screenshot image. + The filename of the file cited. - - `type: :computer_screenshot` + - `index: Integer` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The index of the file in the list of files. - - `:computer_screenshot` + - `type: :file_citation` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The type of the file citation. Always `file_citation`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:file_citation` - - `mode: :explicit` + - `class URLCitation` - The breakpoint mode. Always `explicit`. + A citation for a web resource used to generate a model response. - - `:explicit` + - `end_index: Integer` - - `class BetaResponseInputFile` + The index of the last character of the URL citation in the message. - A file input to the model. + - `start_index: Integer` - - `class EncryptedContent` + The index of the first character of the URL citation in the message. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `title: String` - - `encrypted_content: String` + The title of the web resource. - Opaque encrypted content. + - `type: :url_citation` - - `type: :encrypted_content` + The type of the URL citation. Always `url_citation`. - The type of the input item. Always `encrypted_content`. + - `:url_citation` - - `:encrypted_content` + - `url: String` - - `recipient: String` + The URL of the web resource. - The destination agent identity. + - `class ContainerFileCitation` - - `type: :agent_message` + A citation for a container file used to generate a model response. - The type of the item. Always `agent_message`. + - `container_id: String` - - `:agent_message` + The ID of the container file. - - `agent: Agent{ agent_name}` + - `end_index: Integer` - The agent that produced this item. + The index of the last character of the container file citation in the message. - - `agent_name: String` + - `file_id: String` - The canonical name of the agent that produced this item. + The ID of the file. - - `class MultiAgentCall` + - `filename: String` - - `id: String` + The filename of the container file cited. - The unique ID of the multi-agent call item. + - `start_index: Integer` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The index of the first character of the container file citation in the message. - The multi-agent action to execute. + - `type: :container_file_citation` - - `:spawn_agent` + The type of the container file citation. Always `container_file_citation`. - - `:interrupt_agent` + - `:container_file_citation` - - `:list_agents` + - `class FilePath` - - `:send_message` + A path to a file. - - `:followup_task` + - `file_id: String` - - `:wait_agent` + The ID of the file. - - `arguments: String` + - `index: Integer` - The JSON string of arguments generated for the action. + The index of the file in the list of files. - - `call_id: String` + - `type: :file_path` - The unique ID linking this call to its output. + The type of the file path. Always `file_path`. - - `type: :multi_agent_call` + - `:file_path` - The type of the multi-agent call. Always `multi_agent_call`. + - `text: String` - - `:multi_agent_call` + The text output from the model. - - `agent: Agent{ agent_name}` + - `type: :output_text` - The agent that produced this item. + The type of the output text. Always `output_text`. - - `agent_name: String` + - `:output_text` - The canonical name of the agent that produced this item. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `class MultiAgentCallOutput` + - `token: String` - - `id: String` + - `bytes: Array[Integer]` - The unique ID of the multi-agent call output item. + - `logprob: Float` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - The multi-agent action that produced this result. + - `token: String` - - `:spawn_agent` + - `bytes: Array[Integer]` - - `:interrupt_agent` + - `logprob: Float` - - `:list_agents` + - `class BetaResponseOutputRefusal` - - `:send_message` + A refusal from the model. - - `:followup_task` + - `refusal: String` - - `:wait_agent` + The refusal explanation from the model. - - `call_id: String` + - `type: :refusal` - The unique ID of the multi-agent call. + The type of the refusal. Always `refusal`. - - `output: Array[BetaResponseOutputText]` + - `:refusal` - Text output returned by the multi-agent action. + - `role: :assistant` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The role of the output message. Always `assistant`. - The annotations of the text output. + - `:assistant` - - `text: String` + - `status: :in_progress | :completed | :incomplete` - The text output from the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `type: :output_text` + - `:in_progress` - The type of the output text. Always `output_text`. + - `:completed` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:incomplete` - - `type: :multi_agent_call_output` + - `type: :message` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the output message. Always `message`. - - `:multi_agent_call_output` + - `:message` - `agent: Agent{ agent_name}` @@ -106635,109 +118763,91 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch` - - 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. + - `phase: :commentary | :final_answer` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + 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. - 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). + - `:commentary` - - `class Search` + - `:final_answer` - Action type "search" - Performs a web search query. + - `class BetaResponseFileSearchToolCall` - - `type: :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. - The action type. + - `id: String` - - `:search` + The unique ID of the file search tool call. - `queries: Array[String]` - The search queries. - - - `query: String` - - The search query. - - - `sources: Array[Source{ type, url}]` - - The sources used in the search. - - - `type: :url` - - The type of source. Always `url`. - - - `:url` - - - `url: String` - - The URL of the source. + The queries used to search for files. - - `class OpenPage` + - `status: :in_progress | :searching | :completed | 2 more` - Action type "open_page" - Opens a specific URL from search results. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: :open_page` + - `:in_progress` - The action type. + - `:searching` - - `:open_page` + - `:completed` - - `url: String` + - `:incomplete` - The URL opened by the model. + - `:failed` - - `class FindInPage` + - `type: :file_search_call` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the file search tool call. Always `file_search_call`. - - `pattern: String` + - `:file_search_call` - The pattern or text to search for within the page. + - `agent: Agent{ agent_name}` - - `type: :find_in_page` + The agent that produced this item. - The action type. + - `agent_name: String` - - `:find_in_page` + The canonical name of the agent that produced this item. - - `url: String` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - The URL of the page searched for the pattern. + The results of the file search tool call. - - `status: :in_progress | :searching | :completed | :failed` + - `attributes: Hash[Symbol, String | Float | bool]` - The status of the web search tool call. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `:in_progress` + - `String = String` - - `:searching` + - `Float = Float` - - `:completed` + - `UnionMember2 = bool` - - `:failed` + - `file_id: String` - - `type: :web_search_call` + The unique ID of the file. - The type of the web search tool call. Always `web_search_call`. + - `filename: String` - - `:web_search_call` + The name of the file. - - `agent: Agent{ agent_name}` + - `score: Float` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - `class BetaResponseComputerToolCall` @@ -107029,11 +119139,9 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem` - - - `id: String` + - `class ComputerCallOutput` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: String` @@ -107058,29 +119166,19 @@ puts(beta_compacted_response) The URL of the screenshot image. - - `status: :completed | :incomplete | :failed | :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` + - `id: String` + + The ID of the computer tool call output. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The safety checks reported by the API that have been acknowledged by the - developer. + The safety checks reported by the API that have been acknowledged by the developer. - `id: String` @@ -107102,40 +119200,111 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `status: :in_progress | :completed | :incomplete` - The identifier of the actor that created the item. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `class BetaResponseReasoningItem` + - `:in_progress` - 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). + - `:completed` + + - `:incomplete` + + - `class BetaResponseFunctionWebSearch` + + 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 identifier of the reasoning content. + The unique ID of the web search tool call. - - `summary: Array[Summary{ text, type}]` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - Reasoning summary content. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `text: String` + - `class Search` - A summary of the reasoning output from the model so far. + Action type "search" - Performs a web search query. - - `type: :summary_text` + - `type: :search` - The type of the object. Always `summary_text`. + The action type. - - `:summary_text` + - `:search` - - `type: :reasoning` + - `queries: Array[String]` - The type of the object. Always `reasoning`. + The search queries. - - `:reasoning` + - `query: String` + + The search query. + + - `sources: Array[Source{ type, url}]` + + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` + + - `url: String` + + The URL of the source. + + - `class OpenPage` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: :open_page` + + The action type. + + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + 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 | :searching | :completed | :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: Agent{ agent_name}` @@ -107145,24 +119314,64 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `content: Array[Content{ text, type}]` + - `class BetaResponseFunctionToolCall` - Reasoning text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `text: String` + - `arguments: String` - The reasoning text from the model. + A JSON string of the arguments to pass to the function. - - `type: :reasoning_text` + - `call_id: String` - The type of the reasoning text. Always `reasoning_text`. + The unique ID of the function tool call generated by the model. - - `:reasoning_text` + - `name: String` - - `encrypted_content: String` + The name of the function to run. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: :function_call` + + The type of the function tool call. Always `function_call`. + + - `:function_call` + + - `id: String` + + The unique ID of the function tool call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` @@ -107175,29 +119384,145 @@ puts(beta_compacted_response) - `:incomplete` - - `class Program` - - - `id: String` + - `class FunctionCallOutput` - The unique ID of the program item. + The output of a function tool call. - `call_id: String` - The stable call ID of the program item. + The unique ID of the function tool call generated by the model. - - `code: String` + - `output: String | BetaResponseFunctionCallOutputItemList` - The JavaScript source executed by programmatic tool calling. + Text, image, or file output of the function tool call. - - `fingerprint: String` + - `String = String` - Opaque program replay fingerprint that must be round-tripped. + A JSON string of the output of the function tool call. - - `type: :program` + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - The type of the item. Always `program`. + An array of content outputs (text, image, file) for the function tool call. - - `:program` + - `class BetaResponseInputTextContent` + + 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputImageContent` + + 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`. + + - `:input_image` + + - `detail: :low | :high | :auto | :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: String` + + The ID of the file to be sent to the model. + + - `image_url: 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: PromptCacheBreakpoint{ 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` + + - `class BetaResponseInputFileContent` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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: String` + + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -107207,33 +119532,87 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `id: String` + The execution context that produced this tool call. - The unique ID of the program output item. + - `class Direct` - - `call_id: String` + - `type: :direct` - The call ID of the program item. + The caller type. Always `direct`. - - `result: String` + - `:direct` - The result produced by the program item. + - `class Program` - - `status: :completed | :incomplete` + - `caller_id: String` - The terminal status of the program output item. + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `:in_progress` - `:completed` - `:incomplete` - - `type: :program_output` + - `class AgentMessage` - The type of the item. Always `program_output`. + A message routed between agents. - - `:program_output` + - `author: String` + + The sending agent identity. + + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent` + + 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: String` + + The unique ID of this agent message item. - `agent: Agent{ agent_name}` @@ -107243,43 +119622,171 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall` + - `class MultiAgentCall` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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: String` - The unique ID of the tool search call item. + The unique ID of this multi-agent call. - - `arguments: untyped` + - `agent: Agent{ agent_name}` - Arguments used for the tool search call. + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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 tool search call generated by the model. + The unique ID of the multi-agent call. - - `execution: :server | :client` + - `output: Array[Output{ text, type, annotations}]` - Whether tool search was executed by the server or by the client. + Text output returned by the multi-agent action. - - `:server` + - `text: String` - - `:client` + The text content. - - `status: :in_progress | :completed | :incomplete` + - `type: :output_text` - The status of the tool search call item that was recorded. + The content type. Always `output_text`. - - `:in_progress` + - `:output_text` - - `:completed` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `:incomplete` + Citations associated with the text content. - - `type: :tool_search_call` + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - The type of the item. Always `tool_search_call`. + - `file_id: String` - - `:tool_search_call` + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The citation type. Always `file_citation`. + + - `:file_citation` + + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + + - `end_index: Integer` + + The index of the last character of the citation in the message. + + - `start_index: Integer` + + 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. + + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + - `container_id: String` + + The ID of the container. + + - `end_index: Integer` + + 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: Integer` + + 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: String` + + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -107289,15 +119796,29 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `class ToolSearchCall` - The identifier of the actor that created the item. + - `arguments: untyped` - - `class BetaResponseToolSearchOutputItem` + The arguments supplied to the tool search call. + + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` - `id: String` - The unique ID of the tool search output item. + The unique ID of this tool search call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. - `call_id: String` @@ -107313,7 +119834,7 @@ puts(beta_compacted_response) - `status: :in_progress | :completed | :incomplete` - The status of the tool search output item that was recorded. + The status of the tool search call. - `:in_progress` @@ -107321,9 +119842,11 @@ puts(beta_compacted_response) - `:incomplete` + - `class BetaResponseToolSearchOutputItemParam` + - `tools: Array[BetaTool]` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool` @@ -107422,7 +119945,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -107432,7 +119955,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -107479,7 +120006,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -107489,7 +120016,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -108413,10 +120944,14 @@ puts(beta_compacted_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: String` + + The unique ID of this tool search output. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -108425,39 +120960,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `call_id: String` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `class AdditionalTools` + - `execution: :server | :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 | :user | :assistant | 5 more` + - `:client` - The role that provided the additional tools. + - `status: :in_progress | :completed | :incomplete` - - `:unknown` + The status of the tool search output. - - `:user` + - `:in_progress` - - `:assistant` + - `:completed` - - `:system` + - `:incomplete` - - `:critic` + - `class AdditionalTools` - - `:discriminator` + - `role: :developer` - - `:developer` + The role that provided the additional tools. Only `developer` is supported. - - `:tool` + - `:developer` - `tools: Array[BetaTool]` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool` @@ -108525,10 +121060,14 @@ puts(beta_compacted_response) - `type: :additional_tools` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `:additional_tools` + - `id: String` + + The unique ID of this additional tools item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -108537,17 +121076,82 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` + - `class BetaResponseReasoningItem` - 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](https://platform.openai.com/docs/guides/conversation-state). - `id: String` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `summary: Array[Summary{ 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ 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: String` - The encrypted content that was produced by compaction. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseCompactionItemParam` + + 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` @@ -108555,6 +121159,10 @@ puts(beta_compacted_response) - `:compaction` + - `id: String` + + The ID of the compaction item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -108563,10 +121171,6 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - `class ImageGenerationCall` An image generation request made by the model. @@ -108784,13 +121388,9 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseFunctionShellToolCall` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: String` + - `class ShellCall` - 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: Action{ commands, max_output_length, timeout_ms}` @@ -108798,60 +121398,30 @@ puts(beta_compacted_response) - `commands: Array[String]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Integer` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Integer` - Optional timeout in milliseconds for the commands. + 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 | BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class BetaResponseContainerReference` - - Represents a container created with /v1/containers. - - - `container_id: String` - - - `type: :container_reference` - - The environment type. Always `container_reference`. - - - `:container_reference` - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -108868,6 +121438,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -108878,35 +121450,43 @@ puts(beta_compacted_response) - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `environment: BetaLocalEnvironment | BetaContainerReference` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput` + - `class BetaLocalEnvironment` - The output of a shell tool call that was emitted. + - `class BetaContainerReference` - - `id: String` + - `status: :in_progress | :completed | :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: Integer` + - `:incomplete` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput` - - `output: Array[Output{ 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[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Timeout{ type} | Exit{ 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. - `class Timeout` @@ -108924,7 +121504,7 @@ puts(beta_compacted_response) - `exit_code: Integer` - Exit code from the shell process. + The exit code returned by the shell process. - `type: :exit` @@ -108934,32 +121514,22 @@ puts(beta_compacted_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: String` - - The identifier of the actor that created the item. - - - `status: :in_progress | :completed | :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: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -108976,6 +121546,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -108986,19 +121558,27 @@ puts(beta_compacted_response) - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `max_output_length: Integer` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall` + - `status: :in_progress | :completed | :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` + + - `class ApplyPatchCall` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: String` @@ -109006,55 +121586,55 @@ puts(beta_compacted_response) - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ 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. - `class CreateFile` - 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` - `class DeleteFile` - 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` - `class UpdateFile` - 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` @@ -109072,6 +121652,10 @@ puts(beta_compacted_response) - `:apply_patch_call` + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -109088,6 +121672,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -109098,19 +121684,13 @@ puts(beta_compacted_response) - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `:program` - - `id: String` + - `class ApplyPatchCallOutput` - 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` @@ -109130,6 +121710,10 @@ puts(beta_compacted_response) - `:apply_patch_call_output` + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -109146,6 +121730,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -109156,76 +121742,13 @@ puts(beta_compacted_response) - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call output. - - - `output: String` - - Optional textual output returned by the apply patch tool. - - - `class McpCall` - - 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `approval_request_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. - - - `error: String` + The caller type. Always `program`. - The error from the tool call, if any. + - `:program` - `output: String` - The output from the tool call. - - - `status: :in_progress | :completed | :incomplete | 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). - `class McpListTools` @@ -109315,10 +121838,6 @@ puts(beta_compacted_response) 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. @@ -109333,6 +121852,10 @@ puts(beta_compacted_response) - `:mcp_approval_response` + - `id: String` + + The unique ID of the approval response + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -109345,31 +121868,31 @@ puts(beta_compacted_response) Optional reason for the decision. - - `class BetaResponseCustomToolCall` + - `class McpCall` - 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: String` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `:mcp_call` - `agent: Agent{ agent_name}` @@ -109379,536 +121902,554 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `approval_request_id: 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. - - `class Direct` + - `error: String` - - `type: :direct` + The error from the tool call, if any. - - `:direct` + - `output: String` - - `class Program` + The output from the tool call. - - `caller_id: String` + - `status: :in_progress | :completed | :incomplete | 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: String` + - `:incomplete` - The namespace of the custom tool being called. + - `:calling` - - `class BetaResponseCustomToolCallOutputItem` + - `:failed` + + - `class BetaResponseCustomToolCallOutput` The output of a custom tool call from your code, being sent back to the model. - - `id: String` + - `call_id: String` - The unique ID of the custom tool call output item. + The call ID, used to map this custom tool call output to a custom tool call. - - `status: :in_progress | :completed | :incomplete` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `:in_progress` + - `String = String` - - `:completed` + A string of the output of the custom tool call. - - `:incomplete` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `created_by: String` + Text, image, or file output of the custom tool call. - The identifier of the actor that created the item. + - `class BetaResponseInputText` -### Beta Response Output Item Added Event + A text input to the model. -- `class BetaResponseOutputItemAddedEvent` + - `class BetaResponseInputImage` - Emitted when a new output item is added. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `item: BetaResponseOutputItem` + - `class BetaResponseInputFile` - The output item that was added. + A file input to the model. - - `class BetaResponseOutputMessage` + - `type: :custom_tool_call_output` - An output message from the model. + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `:custom_tool_call_output` - `id: String` - The unique ID of the output message. + The unique ID of the custom tool call output in the OpenAI platform. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `agent: Agent{ agent_name}` - The content of the output message. + The agent that produced this item. - - `class BetaResponseOutputText` + - `agent_name: String` - A text output from the model. + The canonical name of the agent that produced this item. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The annotations of the text output. + The execution context that produced this tool call. - - `class FileCitation` + - `class Direct` - A citation to a file. + - `type: :direct` - - `file_id: String` + The caller type. Always `direct`. - The ID of the file. + - `:direct` - - `filename: String` + - `class Program` - The filename of the file cited. + - `caller_id: String` - - `index: Integer` + 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_citation` + The caller type. Always `program`. - The type of the file citation. Always `file_citation`. + - `:program` - - `:file_citation` + - `class BetaResponseCustomToolCall` - - `class URLCitation` + A call to a custom tool created by the model. - A citation for a web resource used to generate a model response. + - `call_id: String` - - `end_index: Integer` + An identifier used to map this custom tool call to a tool call output. - The index of the last character of the URL citation in the message. + - `input: String` - - `start_index: Integer` + The input for the custom tool call generated by the model. - The index of the first character of the URL citation in the message. + - `name: String` - - `title: String` + The name of the custom tool being called. - The title of the web resource. + - `type: :custom_tool_call` - - `type: :url_citation` + The type of the custom tool call. Always `custom_tool_call`. - The type of the URL citation. Always `url_citation`. + - `:custom_tool_call` - - `:url_citation` + - `id: String` - - `url: String` + The unique ID of the custom tool call in the OpenAI platform. - The URL of the web resource. + - `agent: Agent{ agent_name}` - - `class ContainerFileCitation` + The agent that produced this item. - A citation for a container file used to generate a model response. + - `agent_name: String` - - `container_id: String` + The canonical name of the agent that produced this item. - The ID of the container file. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `end_index: Integer` + The execution context that produced this tool call. - The index of the last character of the container file citation in the message. + - `class Direct` - - `file_id: String` + - `type: :direct` - The ID of the file. + - `:direct` - - `filename: String` + - `class Program` - The filename of the container file cited. + - `caller_id: String` - - `start_index: Integer` + The call ID of the program item that produced this tool call. - The index of the first character of the container file citation in the message. + - `type: :program` - - `type: :container_file_citation` + - `:program` - The type of the container file citation. Always `container_file_citation`. + - `namespace: String` - - `:container_file_citation` + The namespace of the custom tool being called. - - `class FilePath` + - `class CompactionTrigger` - A path to a file. + Compacts the current context. Must be the final input item. - - `file_id: String` + - `type: :compaction_trigger` - The ID of the file. + The type of the item. Always `compaction_trigger`. - - `index: Integer` + - `:compaction_trigger` - The index of the file in the list of files. + - `agent: Agent{ agent_name}` - - `type: :file_path` + The agent that produced this item. - The type of the file path. Always `file_path`. + - `agent_name: String` - - `:file_path` + The canonical name of the agent that produced this item. - - `text: String` + - `class ItemReference` - The text output from the model. + An internal identifier for an item to reference. - - `type: :output_text` + - `id: String` - The type of the output text. Always `output_text`. + The ID of the item to reference. - - `:output_text` + - `agent: Agent{ agent_name}` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The agent that produced this item. - - `token: String` + - `agent_name: String` - - `bytes: Array[Integer]` + The canonical name of the agent that produced this item. - - `logprob: Float` + - `type: :item_reference` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + The type of item to reference. Always `item_reference`. - - `token: String` + - `:item_reference` - - `bytes: Array[Integer]` + - `class Program` - - `logprob: Float` + - `id: String` - - `class BetaResponseOutputRefusal` + The unique ID of this program item. - A refusal from the model. + - `call_id: String` - - `refusal: String` + The stable call ID of the program item. - The refusal explanation from the model. + - `code: String` - - `type: :refusal` + The JavaScript source executed by programmatic tool calling. - The type of the refusal. Always `refusal`. + - `fingerprint: String` - - `:refusal` + Opaque program replay fingerprint that must be round-tripped. - - `role: :assistant` + - `type: :program` - The role of the output message. Always `assistant`. + The item type. Always `program`. - - `:assistant` + - `:program` - - `status: :in_progress | :completed | :incomplete` + - `agent: Agent{ 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` + - `class ProgramOutput` - - `type: :message` + - `id: String` - The type of the output message. Always `message`. + The unique ID of this program output item. - - `:message` + - `call_id: String` - - `agent: Agent{ 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 | :incomplete` - - `phase: :commentary` + The terminal status of the program output. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `:completed` - - `:commentary` + - `:incomplete` - - `class BetaResponseFileSearchToolCall` + - `type: :program_output` - 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 item type. Always `program_output`. - - `id: String` + - `:program_output` - The unique ID of the file search tool call. + - `agent: Agent{ agent_name}` - - `queries: Array[String]` + The agent that produced this item. - The queries used to search for files. + - `agent_name: String` - - `status: :in_progress | :searching | :completed | 2 more` + The canonical name of the agent that produced this item. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `metadata: Hash[Symbol, String]` - - `: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. - - `:searching` + 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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](https://platform.openai.com/docs/models) + to browse and compare available models. - - `:failed` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - - `type: :file_search_call` + 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 file search tool call. Always `file_search_call`. + - `:"gpt-5.6-sol"` - - `:file_search_call` + - `:"gpt-5.6-terra"` - - `agent: Agent{ agent_name}` + - `:"gpt-5.6-luna"` - The agent that produced this item. + - `:"gpt-5.4"` - - `agent_name: String` + - `:"gpt-5.4-mini"` - The canonical name of the agent that produced this item. + - `:"gpt-5.4-nano"` - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `:"gpt-5.4-mini-2026-03-17"` - The results of the file search tool call. + - `:"gpt-5.4-nano-2026-03-17"` - - `attributes: Hash[Symbol, String | Float | bool]` + - `:"gpt-5.3-chat-latest"` - Set of 16 key-value pairs that can be attached to an object. 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. + - `:"gpt-5.2"` - - `String = String` + - `:"gpt-5.2-2025-12-11"` - - `Float = Float` + - `:"gpt-5.2-chat-latest"` - - `UnionMember2 = bool` + - `:"gpt-5.2-pro"` - - `file_id: String` + - `:"gpt-5.2-pro-2025-12-11"` - The unique ID of the file. + - `:"gpt-5.1"` - - `filename: String` + - `:"gpt-5.1-2025-11-13"` - The name of the file. + - `:"gpt-5.1-codex"` - - `score: Float` + - `:"gpt-5.1-mini"` - The relevance score of the file - a value between 0 and 1. + - `:"gpt-5.1-chat-latest"` - - `text: String` + - `:"gpt-5"` - The text that was retrieved from the file. + - `:"gpt-5-mini"` - - `class BetaResponseFunctionToolCall` + - `:"gpt-5-nano"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `:"gpt-5-2025-08-07"` - - `arguments: String` + - `:"gpt-5-mini-2025-08-07"` - A JSON string of the arguments to pass to the function. + - `:"gpt-5-nano-2025-08-07"` - - `call_id: String` + - `:"gpt-5-chat-latest"` - The unique ID of the function tool call generated by the model. + - `:"gpt-4.1"` - - `name: String` + - `:"gpt-4.1-mini"` - The name of the function to run. + - `:"gpt-4.1-nano"` - - `type: :function_call` + - `:"gpt-4.1-2025-04-14"` - The type of the function tool call. Always `function_call`. + - `:"gpt-4.1-mini-2025-04-14"` - - `:function_call` + - `:"gpt-4.1-nano-2025-04-14"` - - `id: String` + - `:"o4-mini"` - The unique ID of the function tool call. + - `:"o4-mini-2025-04-16"` - - `agent: Agent{ agent_name}` + - `:o3` - The agent that produced this item. + - `:"o3-2025-04-16"` - - `agent_name: String` + - `:"o3-mini"` - The canonical name of the agent that produced this item. + - `:"o3-mini-2025-01-31"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:o1` - The execution context that produced this tool call. + - `:"o1-2024-12-17"` - - `class Direct` + - `:"o1-preview"` - - `type: :direct` + - `:"o1-preview-2024-09-12"` - - `:direct` + - `:"o1-mini"` - - `class Program` + - `:"o1-mini-2024-09-12"` - - `caller_id: String` + - `:"gpt-4o"` - The call ID of the program item that produced this tool call. + - `:"gpt-4o-2024-11-20"` - - `type: :program` + - `:"gpt-4o-2024-08-06"` - - `:program` + - `:"gpt-4o-2024-05-13"` - - `namespace: String` + - `:"gpt-4o-audio-preview"` - The namespace of the function to run. + - `:"gpt-4o-audio-preview-2024-10-01"` - - `status: :in_progress | :completed | :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"` - - `class BetaResponseFunctionToolCallOutputItem` + - `:"gpt-4o-mini-search-preview"` - - `id: String` + - `:"gpt-4o-search-preview-2025-03-11"` - The unique ID of the function call tool output. + - `:"gpt-4o-mini-search-preview-2025-03-11"` - - `call_id: String` + - `:"chatgpt-4o-latest"` - The unique ID of the function tool call generated by the model. + - `:"codex-mini-latest"` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:"gpt-4o-mini"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `:"gpt-4o-mini-2024-07-18"` - - `String = String` + - `:"gpt-4-turbo"` - A string of the output of the function call. + - `:"gpt-4-turbo-2024-04-09"` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:"gpt-4-0125-preview"` - Text, image, or file output of the function call. + - `:"gpt-4-turbo-preview"` - - `class BetaResponseInputText` + - `:"gpt-4-1106-preview"` - A text input to the model. + - `:"gpt-4-vision-preview"` - - `text: String` + - `:"gpt-4"` - The text input to the model. + - `:"gpt-4-0314"` - - `type: :input_text` + - `:"gpt-4-0613"` - The type of the input item. Always `input_text`. + - `:"gpt-4-32k"` - - `:input_text` + - `:"gpt-4-32k-0314"` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"gpt-4-32k-0613"` - Marks the exact end of a reusable 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-3.5-turbo"` - - `mode: :explicit` + - `:"gpt-3.5-turbo-16k"` - The breakpoint mode. Always `explicit`. + - `:"gpt-3.5-turbo-0301"` - - `:explicit` + - `:"gpt-3.5-turbo-0613"` - - `class BetaResponseInputImage` + - `:"gpt-3.5-turbo-1106"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:"gpt-3.5-turbo-0125"` - - `detail: :low | :high | :auto | :original` + - `:"gpt-3.5-turbo-16k-0613"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:"o1-pro"` - - `:low` + - `:"o1-pro-2025-03-19"` - - `:high` + - `:"o3-pro"` - - `:auto` + - `:"o3-pro-2025-06-10"` - - `:original` + - `:"o3-deep-research"` - - `type: :input_image` + - `:"o3-deep-research-2025-06-26"` - The type of the input item. Always `input_image`. + - `:"o4-mini-deep-research"` - - `:input_image` + - `:"o4-mini-deep-research-2025-06-26"` - - `file_id: String` + - `:"computer-use-preview"` - The ID of the file to be sent to the model. + - `:"computer-use-preview-2025-03-11"` - - `image_url: String` + - `:"gpt-5-codex"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `:"gpt-5-pro"` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"gpt-5-pro-2025-10-06"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:"gpt-5.1-codex-max"` - - `mode: :explicit` + - `String = String` - The breakpoint mode. Always `explicit`. + - `object: :response` - - `:explicit` + The object type of this resource - always set to `response`. + + - `:response` + + - `output: Array[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. - - `class BetaResponseInputFile` + - `class BetaResponseOutputMessage` - A file input to the model. + An output message from the model. - - `type: :input_file` + - `class BetaResponseFileSearchToolCall` - The type of the input item. Always `input_file`. + 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. - - `:input_file` + - `class BetaResponseFunctionToolCall` - - `detail: :auto | :low | :high` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - 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`. + - `class BetaResponseFunctionToolCallOutputItem` - - `:auto` + - `id: String` - - `:low` + The unique ID of the function call tool output. - - `:high` + - `call_id: String` - - `file_data: String` + The unique ID of the function tool call generated by the model. - The content of the file to be sent to the model. + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `file_id: String` + The output from the function call generated by your code. + Can be a string or an list of output content. - The ID of the file to be sent to the model. + - `String = String` - - `file_url: String` + A string of the output of the function call. - The URL of the file to be sent to the model. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `filename: String` + Text, image, or file output of the function call. - The name of the file to be sent to the model. + - `class BetaResponseInputText` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + A text input to the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaResponseInputImage` - - `mode: :explicit` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The breakpoint mode. Always `explicit`. + - `class BetaResponseInputFile` - - `:explicit` + A file input to the model. - `status: :in_progress | :completed | :incomplete` @@ -110214,395 +122755,11 @@ puts(beta_compacted_response) 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: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). - - - `class Search` - - Action type "search" - Performs a web search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `query: String` - - The search query. - - - `sources: Array[Source{ type, url}]` - - The sources used in the search. - - - `type: :url` - - The type of source. Always `url`. - - - `:url` - - - `url: String` - - The URL of the source. - - - `class OpenPage` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: :open_page` - - The action type. - - - `:open_page` - - - `url: String` - - The URL opened by the model. - - - `class FindInPage` - - 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 | :searching | :completed | :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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall` 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[PendingSafetyCheck{ id, code, message}]` - - The pending safety checks for the computer call. - - - `id: String` - - The ID of the pending safety check. - - - `code: String` - - The type of the pending safety check. - - - `message: String` - - Details about the pending safety check. - - - `status: :in_progress | :completed | :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: BetaComputerAction` - - A click action. - - - `class Click` - - A click action. - - - `button: :left | :right | :wheel | 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: Integer` - - The x-coordinate where the click occurred. - - - `y_: Integer` - - The y-coordinate where the click occurred. - - - `keys: Array[String]` - - The keys being held while clicking. - - - `class DoubleClick` - - A double click action. - - - `keys: Array[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: Integer` - - The x-coordinate where the double click occurred. - - - `y_: Integer` - - The y-coordinate where the double click occurred. - - - `class Drag` - - A drag action. - - - `path: Array[Path{ 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: Integer` - - The x-coordinate. - - - `y_: Integer` - - The y-coordinate. - - - `type: :drag` - - Specifies the event type. For a drag action, this property is always set to `drag`. - - - `:drag` - - - `keys: Array[String]` - - The keys being held while dragging the mouse. - - - `class Keypress` - - A collection of keypresses the model would like to perform. - - - `keys: Array[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` - - - `class Move` - - A mouse move action. - - - `type: :move` - - Specifies the event type. For a move action, this property is always set to `move`. - - - `:move` - - - `x: Integer` - - The x-coordinate to move to. - - - `y_: Integer` - - The y-coordinate to move to. - - - `keys: Array[String]` - - The keys being held while moving the mouse. - - - `class Screenshot` - - A screenshot action. - - - `type: :screenshot` - - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - - `:screenshot` - - - `class Scroll` - - A scroll action. - - - `scroll_x: Integer` - - The horizontal scroll distance. - - - `scroll_y: Integer` - - The vertical scroll distance. - - - `type: :scroll` - - Specifies the event type. For a scroll action, this property is always set to `scroll`. - - - `:scroll` - - - `x: Integer` - - The x-coordinate where the scroll occurred. - - - `y_: Integer` - - The y-coordinate where the scroll occurred. - - - `keys: Array[String]` - - The keys being held while scrolling. - - - `class 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` - - - `class Wait` - - A wait action. - - - `type: :wait` - - Specifies the event type. For a wait action, this property is always set to `wait`. - - - `:wait` - - - `actions: BetaComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `class Click` - - A click action. - - - `class DoubleClick` - - A double click action. - - - `class Drag` - - A drag action. - - - `class Keypress` - - A collection of keypresses the model would like to perform. - - - `class Move` - - A mouse move action. - - - `class Screenshot` - - A screenshot action. - - - `class Scroll` - - A scroll action. - - - `class Type` - - An action to type in text. - - - `class Wait` - - A wait action. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem` - `id: String` @@ -110617,21 +122774,6 @@ puts(beta_compacted_response) 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: String` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: String` - - The URL of the screenshot image. - - `status: :completed | :incomplete | :failed | :in_progress` The status of the message input. One of `in_progress`, `completed`, or @@ -110687,68 +122829,6 @@ puts(beta_compacted_response) 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[Summary{ 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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `content: Array[Content{ 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: String` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - `class Program` - `id: String` @@ -110903,1135 +122983,1152 @@ puts(beta_compacted_response) Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `name: String` + - `class BetaFileSearchTool` - The name of the function to 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). - - `parameters: Hash[Symbol, untyped]` + - `class BetaComputerTool` - A JSON schema object describing the parameters of the function. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `strict: bool` + - `class BetaComputerUsePreviewTool` - Whether strict parameter validation is enforced for this function tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: :function` + - `class BetaWebSearchTool` - The type of the function tool. Always `function`. + 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). - - `:function` + - `class Mcp` - - `allowed_callers: Array[:direct | :programmatic]` + 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 tool invocation context(s). + - `class CodeInterpreter` - - `:direct` + A tool that runs Python code to help generate a response to a prompt. - - `:programmatic` + - `class ProgrammaticToolCalling` - - `defer_loading: bool` + - `class ImageGeneration` - Whether this function is deferred and loaded via tool search. + A tool that generates images using the GPT image models. - - `description: String` + - `class LocalShell` - A description of the function. Used by the model to determine whether or not to call the function. + A tool that allows the model to execute shell commands in a local environment. - - `output_schema: Hash[Symbol, untyped]` + - `class BetaFunctionShellTool` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A tool that allows the model to execute shell commands. - - `class BetaFileSearchTool` + - `class BetaCustomTool` - 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 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: :file_search` + - `class BetaNamespaceTool` - The type of the file search tool. Always `file_search`. + Groups function/custom tools under a shared namespace. - - `:file_search` + - `class BetaToolSearchTool` - - `vector_store_ids: Array[String]` + Hosted or BYOT tool search configuration for deferred tools. - The IDs of the vector stores to search. + - `class BetaWebSearchPreviewTool` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, 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 filter to apply. + - `class BetaApplyPatchTool` - - `class ComparisonFilter` + Allows the assistant to create, delete, or update files using unified diffs. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: :tool_search_output` - - `key: String` + The type of the item. Always `tool_search_output`. - The key to compare against the value. + - `:tool_search_output` - - `type: :eq | :ne | :gt | 5 more` + - `agent: Agent{ 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` + - `created_by: String` - - `:gt` + The identifier of the actor that created the item. - - `:gte` + - `class AdditionalTools` - - `:lt` + - `id: String` - - `:lte` + The unique ID of the additional tools item. - - `:in` + - `role: :unknown | :user | :assistant | 5 more` - - `:nin` + The role that provided the additional tools. - - `value: String | Float | bool | Array[untyped]` + - `:unknown` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:user` - - `String = String` + - `:assistant` - - `Float = Float` + - `:system` - - `UnionMember2 = bool` + - `:critic` - - `UnionMember3 = Array[untyped]` + - `:discriminator` - - `class CompoundFilter` + - `:developer` - Combine multiple filters using `and` or `or`. + - `:tool` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + - `tools: Array[BetaTool]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The additional tool definitions made available at this item. - - `class ComparisonFilter` + - `class BetaFunctionTool` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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). - - `key: String` + - `class BetaFileSearchTool` - The key to compare against the value. + 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: :eq | :ne | :gt | 5 more` + - `class BetaComputerTool` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class BetaComputerUsePreviewTool` - - `:eq` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:ne` + - `class BetaWebSearchTool` - - `:gt` + 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). - - `:gte` + - `class Mcp` - - `:lt` + 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). - - `:lte` + - `class CodeInterpreter` - - `:in` + A tool that runs Python code to help generate a response to a prompt. - - `:nin` + - `class ProgrammaticToolCalling` - - `value: String | Float | bool | Array[untyped]` + - `class ImageGeneration` - The value to compare against the attribute key; supports string, number, or boolean types. + A tool that generates images using the GPT image models. - - `String = String` + - `class LocalShell` - - `Float = Float` + A tool that allows the model to execute shell commands in a local environment. - - `UnionMember2 = bool` + - `class BetaFunctionShellTool` - - `UnionMember3 = Array[untyped]` + A tool that allows the model to execute shell commands. - - `UnionMember1 = untyped` + - `class BetaCustomTool` - - `type: :and | :or` + 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 of operation: `and` or `or`. + - `class BetaNamespaceTool` - - `:and` + Groups function/custom tools under a shared namespace. - - `:or` + - `class BetaToolSearchTool` - - `max_num_results: Integer` + Hosted or BYOT tool search configuration for deferred tools. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `class BetaWebSearchPreviewTool` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + 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). - Ranking options for search. + - `class BetaApplyPatchTool` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + Allows the assistant to create, delete, or update files using unified diffs. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: :additional_tools` - - `embedding_weight: Float` + The type of the item. Always `additional_tools`. - The weight of the embedding in the reciprocal ranking fusion. + - `:additional_tools` - - `text_weight: Float` + - `agent: Agent{ agent_name}` - The weight of the text in the reciprocal ranking fusion. + The agent that produced this item. - - `ranker: :auto | :"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` + - `class BetaResponseCompactionItem` - - `:"default-2024-11-15"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `score_threshold: Float` + - `id: String` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The unique ID of the compaction item. - - `class BetaComputerTool` + - `encrypted_content: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The encrypted content that was produced by compaction. - - `type: :computer` + - `type: :compaction` - The type of the computer tool. Always `computer`. + The type of the item. Always `compaction`. - - `:computer` + - `:compaction` - - `class BetaComputerUsePreviewTool` + - `agent: Agent{ agent_name}` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `display_height: Integer` + - `agent_name: String` - The height of the computer display. + The canonical name of the agent that produced this item. - - `display_width: Integer` + - `created_by: String` - The width of the computer display. + The identifier of the actor that created the item. - - `environment: :windows | :mac | :linux | 2 more` + - `class ImageGenerationCall` - The type of computer environment to control. + An image generation request made by the model. - - `:windows` + - `id: String` - - `:mac` + The unique ID of the image generation call. - - `:linux` + - `result: String` - - `:ubuntu` + The generated image encoded in base64. - - `:browser` + - `status: :in_progress | :completed | :generating | :failed` - - `type: :computer_use_preview` + The status of the image generation call. - The type of the computer use tool. Always `computer_use_preview`. + - `:in_progress` - - `:computer_use_preview` + - `:completed` - - `class BetaWebSearchTool` + - `:generating` - 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). + - `:failed` - - `type: :web_search | :web_search_2025_08_26` + - `type: :image_generation_call` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The type of the image generation call. Always `image_generation_call`. - - `:web_search` + - `:image_generation_call` - - `:web_search_2025_08_26` + - `agent: Agent{ agent_name}` - - `filters: Filters{ allowed_domains}` + The agent that produced this item. - Filters for the search. + - `agent_name: String` - - `allowed_domains: Array[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. + - `class BetaResponseCodeInterpreterToolCall` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A tool call to run code. - - `search_context_size: :low | :medium | :high` + - `class LocalShellCall` - High 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 to run a command on the local shell. - - `:low` + - `id: String` - - `:medium` + The unique ID of the local shell call. - - `:high` + - `action: Action{ command, env, type, 3 more}` - - `user_location: UserLocation{ city, country, region, 2 more}` + Execute a shell command on the server. - The approximate location of the user. + - `command: Array[String]` - - `city: String` + The command to run. - Free text input for the city of the user, e.g. `San Francisco`. + - `env: Hash[Symbol, String]` - - `country: String` + Environment variables to set for the command. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: :exec` - - `region: String` + The type of the local shell action. Always `exec`. - Free text input for the region of the user, e.g. `California`. + - `:exec` - - `timezone: String` + - `timeout_ms: Integer` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Optional timeout in milliseconds for the command. - - `type: :approximate` + - `user: String` - The type of location approximation. Always `approximate`. + Optional user to run the command as. - - `:approximate` + - `working_directory: String` - - `class Mcp` + Optional working directory to run the command in. - 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). + - `call_id: String` - - `server_label: String` + The unique ID of the local shell tool call generated by the model. - A label for this MCP server, used to identify it in tool calls. + - `status: :in_progress | :completed | :incomplete` - - `type: :mcp` + The status of the local shell call. - The type of the MCP tool. Always `mcp`. + - `:in_progress` - - `:mcp` + - `:completed` - - `allowed_callers: Array[:direct | :programmatic]` + - `:incomplete` - The tool invocation context(s). + - `type: :local_shell_call` - - `:direct` + The type of the local shell call. Always `local_shell_call`. - - `:programmatic` + - `:local_shell_call` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `agent: Agent{ agent_name}` - List of allowed tool names or a filter object. + The agent that produced this item. - - `McpAllowedTools = Array[String]` + - `agent_name: String` - A string array of allowed tool names + The canonical name of the agent that produced this item. - - `class McpToolFilter` + - `class LocalShellCallOutput` - A filter object to specify which tools are allowed. + The output of a local shell tool call. - - `read_only: bool` + - `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 local shell tool call generated by the model. - - `tool_names: Array[String]` + - `output: String` - List of allowed tool names. + A JSON string of the output of the local shell tool call. - - `authorization: String` + - `type: :local_shell_call_output` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:local_shell_call_output` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `agent: Agent{ agent_name}` - Currently supported `connector_id` values are: + 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` + - `agent_name: String` - - `:connector_dropbox` + The canonical name of the agent that produced this item. - - `:connector_gmail` + - `status: :in_progress | :completed | :incomplete` - - `:connector_googlecalendar` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `:connector_googledrive` + - `:in_progress` - - `:connector_microsoftteams` + - `:completed` - - `:connector_outlookcalendar` + - `:incomplete` - - `:connector_outlookemail` + - `class BetaResponseFunctionShellToolCall` - - `:connector_sharepoint` + A tool call that executes one or more shell commands in a managed environment. - - `defer_loading: bool` + - `id: String` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `headers: Hash[Symbol, String]` + - `action: Action{ commands, max_output_length, timeout_ms}` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The shell commands and limits that describe how to run the tool call. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `commands: Array[String]` - Specify which of the MCP server's tools require approval. + - `max_output_length: Integer` - - `class McpToolApprovalFilter` + Optional maximum number of characters to return from each command. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `timeout_ms: Integer` - - `always: Always{ read_only, tool_names}` + Optional timeout in milliseconds for the commands. - A filter object to specify which tools are allowed. + - `call_id: String` - - `read_only: bool` + The unique ID of the shell tool call generated by the model. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `tool_names: Array[String]` + Represents the use of a local environment to perform shell actions. - List of allowed tool names. + - `class BetaResponseLocalEnvironment` - - `never: Never{ read_only, tool_names}` + Represents the use of a local environment to perform shell actions. - A filter object to specify which tools are allowed. + - `type: :local` - - `read_only: bool` + The environment type. Always `local`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `:local` - - `tool_names: Array[String]` + - `class BetaResponseContainerReference` - List of allowed tool names. + Represents a container created with /v1/containers. - - `McpToolApprovalSetting = :always | :never` + - `container_id: String` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: :container_reference` - - `:always` + The environment type. Always `container_reference`. - - `:never` + - `:container_reference` - - `server_description: String` + - `status: :in_progress | :completed | :incomplete` - Optional description of the MCP server, used to provide more context. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `server_url: String` + - `:in_progress` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:completed` - - `tunnel_id: 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: :shell_call` - - `class CodeInterpreter` + The type of the item. Always `shell_call`. - A tool that runs Python code to help generate a response to a prompt. + - `:shell_call` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `agent: Agent{ 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 = String` + - `agent_name: String` - The container ID. + The canonical name of the agent that produced this item. - - `class CodeInterpreterToolAuto` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The execution context that produced this tool call. - - `type: :auto` + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput` + + 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: Integer` - Always `auto`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `:auto` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `file_ids: Array[String]` + An array of shell call output contents - An optional list of uploaded files to make available to your code. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The memory limit for the code interpreter container. + - `class Timeout` - - `:"1g"` + Indicates that the shell call exceeded its configured time limit. - - `:"4g"` + - `type: :timeout` - - `:"16g"` + The outcome type. Always `timeout`. - - `:"64g"` + - `:timeout` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `class Exit` - Network access policy for the container. + Indicates that the shell commands finished and returned an exit code. - - `class BetaContainerNetworkPolicyDisabled` + - `exit_code: Integer` - - `type: :disabled` + Exit code from the shell process. - Disable outbound network access. Always `disabled`. + - `type: :exit` - - `:disabled` + The outcome type. Always `exit`. - - `class BetaContainerNetworkPolicyAllowlist` + - `:exit` - - `allowed_domains: Array[String]` + - `stderr: String` - A list of allowed domains when type is `allowlist`. + The standard error output that was captured. - - `type: :allowlist` + - `stdout: String` - Allow outbound network access only to specified domains. Always `allowlist`. + The standard output that was captured. - - `:allowlist` + - `created_by: String` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + The identifier of the actor that created the item. - Optional domain-scoped secrets for allowlisted domains. + - `status: :in_progress | :completed | :incomplete` - - `domain: String` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The domain associated with the secret. + - `:in_progress` - - `name: String` + - `:completed` - The name of the secret to inject for the domain. + - `:incomplete` - - `value: String` + - `type: :shell_call_output` - The secret value to inject for the domain. + The type of the shell call output. Always `shell_call_output`. - - `type: :code_interpreter` + - `:shell_call_output` - The type of the code interpreter tool. Always `code_interpreter`. + - `agent: Agent{ agent_name}` - - `:code_interpreter` + The agent that produced this item. - - `allowed_callers: Array[:direct | :programmatic]` + - `agent_name: String` - The tool invocation context(s). + The canonical name of the agent that produced this item. - - `:direct` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:programmatic` + The execution context that produced this tool call. - - `class ProgrammaticToolCalling` + - `class Direct` - - `type: :programmatic_tool_calling` + - `type: :direct` - The type of the tool. Always `programmatic_tool_calling`. + - `:direct` - - `:programmatic_tool_calling` + - `class Program` - - `class ImageGeneration` + - `caller_id: String` - A tool that generates images using the GPT image models. + The call ID of the program item that produced this tool call. - - `type: :image_generation` + - `type: :program` - The type of the image generation tool. Always `image_generation`. + - `:program` - - `:image_generation` + - `created_by: String` - - `action: :generate | :edit | :auto` + The identifier of the actor that created the item. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class BetaResponseApplyPatchToolCall` - - `:generate` + A tool call that applies file diffs by creating, deleting, or updating files. - - `:edit` + - `id: String` - - `:auto` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `background: :transparent | :opaque | :auto` + - `call_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 ID of the apply patch tool call generated by 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. + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `:transparent` + - `class CreateFile` - - `:opaque` + Instruction describing how to create a file via the apply_patch tool. - - `:auto` + - `diff: String` - - `input_fidelity: :high | :low` + Diff to apply. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `path: String` - - `:high` + Path of the file to create. - - `:low` + - `type: :create_file` - - `input_image_mask: InputImageMask{ file_id, image_url}` + Create a new file with the provided diff. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `:create_file` - - `file_id: String` + - `class DeleteFile` - File ID for the mask image. + Instruction describing how to delete a file via the apply_patch tool. - - `image_url: String` + - `path: String` - Base64-encoded mask image. + Path of the file to delete. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `type: :delete_file` - The image generation model to use. Default: `gpt-image-1`. + Delete the specified file. - - `String = String` + - `:delete_file` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `class UpdateFile` - The image generation model to use. Default: `gpt-image-1`. + Instruction describing how to update a file via the apply_patch tool. - - `:"gpt-image-1"` + - `diff: String` - - `:"gpt-image-1-mini"` + Diff to apply. - - `:"gpt-image-2"` + - `path: String` - - `:"gpt-image-2-2026-04-21"` + Path of the file to update. - - `:"gpt-image-1.5"` + - `type: :update_file` - - `:"chatgpt-image-latest"` + Update an existing file with the provided diff. - - `moderation: :auto | :low` + - `:update_file` - Moderation level for the generated image. Default: `auto`. + - `status: :in_progress | :completed` - - `:auto` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:low` + - `:in_progress` - - `output_compression: Integer` + - `:completed` - Compression level for the output image. Default: 100. + - `type: :apply_patch_call` - - `output_format: :png | :webp | :jpeg` + The type of the item. Always `apply_patch_call`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `:apply_patch_call` - - `:png` + - `agent: Agent{ agent_name}` - - `:webp` + The agent that produced this item. - - `:jpeg` + - `agent_name: String` - - `partial_images: Integer` + 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_: Direct{ type} | Program{ caller_id, type}` - - `quality: :low | :medium | :high | :auto` + The execution context that produced this tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `class Direct` - - `:low` + - `type: :direct` - - `:medium` + - `:direct` - - `:high` + - `class Program` - - `:auto` + - `caller_id: String` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 = String` + - `:program` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `created_by: 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. - - `:"1024x1024"` + - `class BetaResponseApplyPatchToolCallOutput` - - `:"1024x1536"` + The output emitted by an apply patch tool call. - - `:"1536x1024"` + - `id: String` - - `:auto` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class LocalShell` + - `call_id: String` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the apply patch tool call generated by the model. - - `type: :local_shell` + - `status: :completed | :failed` - The type of the local shell tool. Always `local_shell`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `:local_shell` + - `:completed` - - `class BetaFunctionShellTool` + - `:failed` - A tool that allows the model to execute shell commands. + - `type: :apply_patch_call_output` - - `type: :shell` + The type of the item. Always `apply_patch_call_output`. - The type of the shell tool. Always `shell`. + - `:apply_patch_call_output` - - `:shell` + - `agent: Agent{ agent_name}` - - `allowed_callers: Array[:direct | :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_: Direct{ type} | Program{ caller_id, type}` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + The execution context that produced this tool call. - - `class BetaContainerAuto` + - `class Direct` - - `type: :container_auto` + - `type: :direct` - Automatically creates a container for this request + - `:direct` - - `:container_auto` + - `class Program` - - `file_ids: Array[String]` + - `caller_id: String` - An optional list of uploaded files to make available to your code. + The call ID of the program item that produced this tool call. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `type: :program` - The memory limit for the container. + - `:program` - - `:"1g"` + - `created_by: String` - - `:"4g"` + The ID of the entity that created this tool call output. - - `:"16g"` + - `output: String` - - `:"64g"` + Optional textual output returned by the apply patch tool. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `class McpCall` - Network access policy for the container. + An invocation of a tool on an MCP server. - - `class BetaContainerNetworkPolicyDisabled` + - `id: String` - - `class BetaContainerNetworkPolicyAllowlist` + The unique ID of the tool call. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `arguments: String` - An optional list of skills referenced by id or inline data. + A JSON string of the arguments passed to the tool. - - `class BetaSkillReference` + - `name: String` - - `skill_id: String` + The name of the tool that was run. - The ID of the referenced skill. + - `server_label: String` - - `type: :skill_reference` + The label of the MCP server running the tool. - References a skill created with the /v1/skills endpoint. + - `type: :mcp_call` - - `:skill_reference` + The type of the item. Always `mcp_call`. - - `version: String` + - `:mcp_call` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `agent: Agent{ agent_name}` - - `class BetaInlineSkill` + The agent that produced this item. - - `description: String` + - `agent_name: String` - The description of the skill. + The canonical name of the agent that produced this item. - - `name: String` + - `approval_request_id: String` - The name of the skill. + 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. - - `source: BetaInlineSkillSource` + - `error: String` - Inline skill payload + The error from the tool call, if any. - - `data: String` + - `output: String` - Base64-encoded skill zip bundle. + The output from the tool call. - - `media_type: :"application/zip"` + - `status: :in_progress | :completed | :incomplete | 2 more` - The media type of the inline skill payload. Must be `application/zip`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `:"application/zip"` + - `:in_progress` - - `type: :base64` + - `:completed` - The type of the inline skill source. Must be `base64`. + - `:incomplete` - - `:base64` + - `:calling` - - `type: :inline` + - `:failed` - Defines an inline skill for this request. + - `class McpListTools` - - `:inline` + A list of tools available on an MCP server. - - `class BetaLocalEnvironment` + - `id: String` - - `type: :local` + The unique ID of the list. - Use a local computer environment. + - `server_label: String` - - `:local` + The label of the MCP server. - - `skills: Array[BetaLocalSkill]` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - An optional list of skills. + The tools available on the server. - - `description: String` + - `input_schema: untyped` - The description of the skill. + The JSON schema describing the tool's input. - `name: String` - The name of the skill. - - - `path: String` + The name of the tool. - The path to the directory containing the skill. + - `annotations: untyped` - - `class BetaContainerReference` + Additional annotations about the tool. - - `container_id: String` + - `description: String` - The ID of the referenced container. + The description of the tool. - - `type: :container_reference` + - `type: :mcp_list_tools` - References a container created with the /v1/containers endpoint + The type of the item. Always `mcp_list_tools`. - - `:container_reference` + - `:mcp_list_tools` - - `class BetaCustomTool` + - `agent: Agent{ 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` + - `error: String` - The type of the custom tool. Always `custom`. + Error message if the server could not list tools. - - `:custom` + - `class McpApprovalRequest` - - `allowed_callers: Array[:direct | :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` - - `defer_loading: bool` + A JSON string of arguments for the tool. - Whether this tool should be deferred and discovered via tool search. + - `name: String` - - `description: String` + The name of the tool to run. - Optional description of the custom tool, used to provide more context. + - `server_label: String` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + The label of the MCP server making the request. - The input format for the custom tool. Default is unconstrained text. + - `type: :mcp_approval_request` - - `class Text` + The type of the item. Always `mcp_approval_request`. - Unconstrained free-form text. + - `:mcp_approval_request` - - `type: :text` + - `agent: Agent{ agent_name}` - Unconstrained text format. Always `text`. + The agent that produced this item. - - `:text` + - `agent_name: String` - - `class Grammar` + The canonical name of the agent that produced this item. - A grammar defined by the user. + - `class McpApprovalResponse` - - `definition: String` + A response to an MCP approval request. - The grammar definition. + - `id: String` - - `syntax: :lark | :regex` + The unique ID of the approval response - The syntax of the grammar definition. One of `lark` or `regex`. + - `approval_request_id: String` - - `:lark` + The ID of the approval request being answered. - - `:regex` + - `approve: bool` - - `type: :grammar` + Whether the request was approved. - Grammar format. Always `grammar`. + - `type: :mcp_approval_response` - - `:grammar` + The type of the item. Always `mcp_approval_response`. - - `class BetaNamespaceTool` + - `:mcp_approval_response` - Groups function/custom tools under a shared namespace. + - `agent: Agent{ agent_name}` - - `description: String` + The agent that produced this item. - A description of the namespace shown to the model. + - `agent_name: String` - - `name: String` + The canonical name of the agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `reason: String` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + Optional reason for the decision. - The function/custom tools available inside this namespace. + - `class BetaResponseCustomToolCall` - - `class Function` + A call to a custom tool created by the model. - - `name: String` + - `class BetaResponseCustomToolCallOutputItem` - - `type: :function` + The output of a custom tool call from your code, being sent back to the model. - - `:function` + - `id: String` - - `allowed_callers: Array[:direct | :programmatic]` + The unique ID of the custom tool call output item. - The tool invocation context(s). + - `status: :in_progress | :completed | :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: bool` + - `:completed` - Whether this function should be deferred and discovered via tool search. + - `:incomplete` - - `description: String` + - `created_by: String` - - `output_schema: Hash[Symbol, untyped]` + The identifier of the actor that created the item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parallel_tool_calls: bool` - - `parameters: untyped` + Whether to allow the model to run tool calls in parallel. - - `strict: bool` + - `temperature: Float` - 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. + 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. - - `class BetaCustomTool` + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 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) + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `type: :namespace` + - `BetaToolChoiceOptions = :none | :auto | :required` - The type of the tool. Always `namespace`. + Controls which (if any) tool is called by the model. - - `:namespace` + `none` means the model will not call any tool and instead generates a message. - - `class BetaToolSearchTool` + `auto` means the model can pick between generating a message or calling one or + more tools. - Hosted or BYOT tool search configuration for deferred tools. + `required` means the model must call one or more tools. - - `type: :tool_search` + - `:none` - The type of the tool. Always `tool_search`. + - `:auto` - - `:tool_search` + - `:required` - - `description: String` + - `class BetaToolChoiceAllowed` - 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: :server | :client` + - `mode: :auto | :required` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `:server` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `:client` + `required` requires the model to call one or more of the allowed tools. - - `parameters: untyped` + - `:auto` - Parameter schema for a client-executed tool search tool. + - `:required` - - `class BetaWebSearchPreviewTool` + - `tools: Array[Hash[Symbol, untyped]]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A list of tool definitions that the model should be allowed to call. - - `type: :web_search_preview | :web_search_preview_2025_03_11` + For the Responses API, the list of tool definitions might look like: - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `:web_search_preview` + - `type: :allowed_tools` - - `:web_search_preview_2025_03_11` + Allowed tool configuration type. Always `allowed_tools`. - - `search_content_types: Array[:text | :image]` + - `:allowed_tools` - - `:text` + - `class BetaToolChoiceTypes` - - `:image` + 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_context_size: :low | :medium | :high` + - `type: :file_search | :web_search_preview | :computer | 5 more` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `:low` + Allowed values are: - - `:medium` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `:high` + - `:file_search` - - `user_location: UserLocation{ type, city, country, 2 more}` + - `:web_search_preview` - The user's location. + - `:computer` - - `type: :approximate` + - `:computer_use_preview` - The type of location approximation. Always `approximate`. + - `:computer_use` - - `:approximate` + - `:web_search_preview_2025_03_11` - - `city: String` + - `:image_generation` - Free text input for the city of the user, e.g. `San Francisco`. + - `:code_interpreter` - - `country: String` + - `class BetaToolChoiceFunction` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Use this option to force the model to call a specific function. - - `region: String` + - `name: String` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `timezone: String` + - `type: :function` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + For function calling, the type is always `function`. - - `class BetaApplyPatchTool` + - `:function` - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaToolChoiceMcp` - - `type: :apply_patch` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the tool. Always `apply_patch`. + - `server_label: String` - - `:apply_patch` + The label of the MCP server to use. - - `allowed_callers: Array[:direct | :programmatic]` + - `type: :mcp` - The tool invocation context(s). + For MCP tools, the type is always `mcp`. - - `:direct` + - `:mcp` - - `:programmatic` + - `name: String` - - `type: :tool_search_output` + The name of the tool to call on the server. - The type of the item. Always `tool_search_output`. + - `class BetaToolChoiceCustom` - - `:tool_search_output` + Use this option to force the model to call a specific custom tool. - - `agent: Agent{ agent_name}` + - `name: String` - The agent that produced this item. + The name of the custom tool to call. - - `agent_name: String` + - `type: :custom` - The canonical name of the agent that produced this item. + For custom tool calling, the type is always `custom`. - - `created_by: String` + - `:custom` - The identifier of the actor that created the item. + - `class BetaSpecificProgrammaticToolCallingParam` - - `class AdditionalTools` + - `type: :programmatic_tool_calling` - - `id: String` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the additional tools item. + - `:programmatic_tool_calling` - - `role: :unknown | :user | :assistant | 5 more` + - `class BetaToolChoiceApplyPatch` - The role that provided the additional tools. + Forces the model to call the apply_patch tool when executing a tool call. - - `:unknown` + - `type: :apply_patch` - - `:user` + The tool to call. Always `apply_patch`. - - `:assistant` + - `:apply_patch` - - `:system` + - `class BetaToolChoiceShell` - - `:critic` + Forces the model to call the shell tool when a tool call is required. - - `:discriminator` + - `type: :shell` - - `:developer` + The tool to call. Always `shell`. - - `:tool` + - `:shell` - `tools: Array[BetaTool]` - The additional tool definitions made available at this item. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](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. - `class BetaFunctionTool` @@ -112097,2323 +124194,2417 @@ puts(beta_compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: :additional_tools` + - `top_p: Float` - 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: Agent{ agent_name}` + - `background: bool` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `agent_name: String` + - `completed_at: Float` - 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`. - - `class BetaResponseCompactionItem` + - `conversation: Conversation{ 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: Integer` - 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](https://platform.openai.com/docs/guides/reasoning). - - `type: :compaction` + - `max_tool_calls: Integer` - 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: Moderation{ input, output}` - - `agent: Agent{ agent_name}` + Moderation results for the response input and output, if moderated completions were requested. - The agent that produced this item. + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `agent_name: String` + Moderation for the response input. - The canonical name of the agent that produced this item. + - `class ModerationResult` - - `created_by: String` + A moderation result produced for the response input or output. - The identifier of the actor that created the item. + - `categories: Hash[Symbol, bool]` - - `class ImageGenerationCall` + 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: Hash[Symbol, Array[:text | :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: Hash[Symbol, Float]` - - `status: :in_progress | :completed | :generating | :failed` + A dictionary of moderation categories to scores. - The status of the image generation call. + - `flagged: bool` - - `: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` + - `class Error` - - `agent: Agent{ 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` - - `class BetaResponseCodeInterpreterToolCall` + 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` - - `code: String` + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - The code to run, or null if not available. + Moderation for the response output. - - `container_id: String` + - `class ModerationResult` - The ID of the container used to run the code. + A moderation result produced for the response input or output. - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `categories: Hash[Symbol, bool]` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `class Logs` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - The logs output from the code interpreter. + Which modalities of input are reflected by the score for each category. - - `logs: String` + - `:text` - The logs output from the code interpreter. + - `:image` - - `type: :logs` + - `category_scores: Hash[Symbol, Float]` - The type of the output. Always `logs`. + A dictionary of moderation categories to scores. - - `:logs` + - `flagged: bool` - - `class Image` + A boolean indicating whether the content was flagged by any category. - The image output from the code interpreter. + - `model: String` - - `type: :image` + The moderation model that produced this result. - The type of the output. Always `image`. + - `type: :moderation_result` - - `:image` + The object type, which was always `moderation_result` for successful moderation results. - - `url: String` + - `:moderation_result` - The URL of the image output from the code interpreter. + - `class Error` - - `status: :in_progress | :completed | :incomplete | 2 more` + An error produced while attempting moderation for the response input or output. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `code: String` - - `:in_progress` + The error code. - - `:completed` + - `message: String` - - `:incomplete` + The error message. - - `:interpreting` + - `type: :error` - - `:failed` + The object type, which was always `error` for moderation failures. - - `type: :code_interpreter_call` + - `:error` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `previous_response_id: String` - - `:code_interpreter_call` + 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`. - - `agent: Agent{ agent_name}` + - `prompt: BetaResponsePrompt` - The agent that produced this item. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The unique identifier of the prompt template to use. - - `class LocalShellCall` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - A tool call to run a command on the local shell. + 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. - - `id: String` + - `String = String` - The unique ID of the local shell call. + - `class BetaResponseInputText` - - `action: Action{ command, env, type, 3 more}` + A text input to the model. - Execute a shell command on the server. + - `class BetaResponseInputImage` - - `command: Array[String]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The command to run. + - `class BetaResponseInputFile` - - `env: Hash[Symbol, String]` + A file input to the model. - Environment variables to set for the command. + - `version: String` - - `type: :exec` + Optional version of the prompt template. - The type of the local shell action. Always `exec`. + - `prompt_cache_key: String` - - `:exec` + 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). - - `timeout_ms: Integer` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - Optional timeout in milliseconds for the command. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `user: String` + - `mode: :implicit | :explicit` - Optional user to run the command as. + Whether implicit prompt-cache breakpoints were enabled. - - `working_directory: String` + - `:implicit` - Optional working directory to run the command in. + - `:explicit` - - `call_id: String` + - `ttl: :"30m"` - The unique ID of the local shell tool call generated by the model. + The minimum lifetime applied to each cache breakpoint. - - `status: :in_progress | :completed | :incomplete` + - `:"30m"` - The status of the local shell call. + - `prompt_cache_retention: :in_memory | :"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](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. - - `:incomplete` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: :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. - The type of the local shell call. Always `local_shell_call`. + - `:in_memory` - - `:local_shell_call` + - `:"24h"` - - `agent: Agent{ agent_name}` + - `reasoning: Reasoning{ 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: :auto | :current_turn | :all_turns` - - `class LocalShellCallOutput` + 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 output of a local shell tool call. + - `:auto` - - `id: String` + - `:current_turn` - The unique ID of the local shell tool call generated by the model. + - `:all_turns` - - `output: String` + - `effort: :none | :minimal | :low | 4 more` - A JSON string of the output of the 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. - - `type: :local_shell_call_output` + - `:none` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `:minimal` - - `:local_shell_call_output` + - `:low` - - `agent: Agent{ agent_name}` + - `:medium` - The agent that produced this item. + - `:high` - - `agent_name: String` + - `:xhigh` - The canonical name of the agent that produced this item. + - `:max` - - `status: :in_progress | :completed | :incomplete` + - `generate_summary: :auto | :concise | :detailed` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + **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` - - `class BetaResponseFunctionShellToolCall` + - `:detailed` - A tool call that executes one or more shell commands in a managed environment. + - `mode: String | :standard | :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: Action{ commands, max_output_length, timeout_ms}` + - `String = String` - The shell commands and limits that describe how to run the tool call. + - `Mode = :standard | :pro` - - `commands: Array[String]` + Controls the reasoning execution mode for the request. - - `max_output_length: Integer` + When returned on a response, this is the effective execution mode. - Optional maximum number of characters to return from each command. + - `:standard` + + - `:pro` + + - `summary: :auto | :concise | :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: 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). + + - `service_tier: :auto | :default | :flex | 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](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'. + + 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` - - `timeout_ms: Integer` + - `:scale` - Optional timeout in milliseconds for the commands. + - `:priority` - - `call_id: String` + - `status: BetaResponseStatus` - The unique ID of the shell tool call generated by the model. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `:completed` - Represents the use of a local environment to perform shell actions. + - `:failed` - - `class BetaResponseLocalEnvironment` + - `:in_progress` - Represents the use of a local environment to perform shell actions. + - `:cancelled` - - `type: :local` + - `:queued` - The environment type. Always `local`. + - `:incomplete` - - `:local` + - `text: BetaResponseTextConfig` - - `class BetaResponseContainerReference` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - Represents a container created with /v1/containers. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `container_id: String` + - `format_: BetaResponseFormatTextConfig` - - `type: :container_reference` + An object specifying the format that the model must output. - The environment type. Always `container_reference`. + 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). - - `:container_reference` + The default format is `{ "type": "text" }` with no additional options. - - `status: :in_progress | :completed | :incomplete` + **Not recommended for gpt-4o and newer models:** - The status of the shell call. One of `in_progress`, `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. - - `:in_progress` + - `class Text` - - `:completed` + Default response format. Used to generate text responses. - - `:incomplete` + - `type: :text` - - `type: :shell_call` + The type of response format being defined. Always `text`. - The type of the item. Always `shell_call`. + - `:text` - - `:shell_call` + - `class BetaResponseFormatTextJSONSchemaConfig` - - `agent: Agent{ 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: Hash[Symbol, untyped]` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The execution context that produced this tool call. + - `type: :json_schema` - - `class Direct` + The type of response format being defined. Always `json_schema`. - - `type: :direct` + - `:json_schema` - - `:direct` + - `description: String` - - `class Program` + 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: bool` - 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` + - `class JSONObject` - - `: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. - - `created_by: String` + - `type: :json_object` - The ID of the entity that created this tool call. + The type of response format being defined. Always `json_object`. - - `class BetaResponseFunctionShellToolCallOutput` + - `:json_object` - The output of a shell tool call that was emitted. + - `verbosity: :low | :medium | :high` - - `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 shell call output. Populated when this item is returned via API. + - `:low` - - `call_id: String` + - `:medium` - The unique ID of the shell tool call generated by the model. + - `:high` - - `max_output_length: Integer` + - `top_logprobs: Integer` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw 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. - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `truncation: :auto | :disabled` - An array of shell call output contents + The truncation strategy to use for the model response. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `:auto` - - `class Timeout` + - `:disabled` - Indicates that the shell call exceeded its configured time limit. + - `usage: BetaResponseUsage` - - `type: :timeout` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The outcome type. Always `timeout`. + - `input_tokens: Integer` - - `:timeout` + The number of input tokens. - - `class Exit` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - Indicates that the shell commands finished and returned an exit code. + A detailed breakdown of the input tokens. - - `exit_code: Integer` + - `cache_write_tokens: Integer` - Exit code from the shell process. + The number of input tokens that were written to the cache. - - `type: :exit` + - `cached_tokens: Integer` - The outcome type. Always `exit`. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `:exit` + - `output_tokens: Integer` - - `stderr: String` + The number of output tokens. - The standard error output that was captured. + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - - `stdout: String` + A detailed breakdown of the output tokens. - The standard output that was captured. + - `reasoning_tokens: Integer` - - `created_by: String` + The number of reasoning tokens. - The identifier of the actor that created the item. + - `total_tokens: Integer` - - `status: :in_progress | :completed | :incomplete` + The total number of tokens used. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `user: 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: Integer` - - `:incomplete` + The sequence number for this event. - - `type: :shell_call_output` + - `type: :"response.completed"` - The type of the shell call output. Always `shell_call_output`. + The type of the event. Always `response.completed`. - - `:shell_call_output` + - `:"response.completed"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseContentPartAddedEvent` - The execution context that produced this tool call. + Emitted when a new content part is added. - - `class Direct` + - `content_index: Integer` - - `type: :direct` + The index of the content part that was added. - - `:direct` + - `item_id: String` - - `class Program` + The ID of the output item that the content part was added to. - - `caller_id: String` + - `output_index: Integer` - The call ID of the program item that produced this tool call. + The index of the output item that the content part was added to. - - `type: :program` + - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` - - `:program` + The content part that was added. - - `created_by: String` + - `class BetaResponseOutputText` - The identifier of the actor that created the item. + A text output from the model. - - `class BetaResponseApplyPatchToolCall` + - `class BetaResponseOutputRefusal` - A tool call that applies file diffs by creating, deleting, or updating files. + A refusal from the model. - - `id: String` + - `class ReasoningText` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + 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. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `type: :reasoning_text` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the reasoning text. Always `reasoning_text`. - - `class CreateFile` + - `:reasoning_text` - Instruction describing how to create a file via the apply_patch tool. + - `sequence_number: Integer` - - `diff: String` + The sequence number of this event. - Diff to apply. + - `type: :"response.content_part.added"` - - `path: String` + The type of the event. Always `response.content_part.added`. - Path of the file to create. + - `:"response.content_part.added"` - - `type: :create_file` + - `agent: Agent{ agent_name}` - Create a new file with the provided diff. + The agent that owns this multi-agent streaming event. - - `:create_file` + - `agent_name: String` - - `class DeleteFile` + The canonical name of the agent that produced this item. - Instruction describing how to delete a file via the apply_patch tool. + - `class BetaResponseContentPartDoneEvent` - - `path: String` + Emitted when a content part is done. - Path of the file to delete. + - `content_index: Integer` - - `type: :delete_file` + The index of the content part that is done. - Delete the specified file. + - `item_id: String` - - `:delete_file` + The ID of the output item that the content part was added to. - - `class UpdateFile` + - `output_index: Integer` - Instruction describing how to update a file via the apply_patch tool. + The index of the output item that the content part was added to. - - `diff: String` + - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` - Diff to apply. + The content part that is done. - - `path: String` + - `class BetaResponseOutputText` - Path of the file to update. + A text output from the model. - - `type: :update_file` + - `class BetaResponseOutputRefusal` - Update an existing file with the provided diff. + A refusal from the model. - - `:update_file` + - `class ReasoningText` - - `status: :in_progress | :completed` + Reasoning text from the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `text: String` - - `:in_progress` + The reasoning text from the model. - - `:completed` + - `type: :reasoning_text` - - `type: :apply_patch_call` + The type of the reasoning text. Always `reasoning_text`. - The type of the item. Always `apply_patch_call`. + - `:reasoning_text` - - `:apply_patch_call` + - `sequence_number: Integer` + + 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: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseCreatedEvent` - The execution context that produced this tool call. + An event that is emitted when a response is created. - - `class Direct` + - `response: BetaResponse` - - `type: :direct` + The response that was created. - - `:direct` + - `sequence_number: Integer` - - `class Program` + The sequence number for this event. - - `caller_id: String` + - `type: :"response.created"` - The call ID of the program item that produced this tool call. + The type of the event. Always `response.created`. - - `type: :program` + - `:"response.created"` - - `:program` + - `agent: Agent{ agent_name}` - - `created_by: String` + The agent that owns this multi-agent streaming event. - The ID of the entity that created this tool call. + - `agent_name: String` - - `class BetaResponseApplyPatchToolCallOutput` + The canonical name of the agent that produced this item. - The output emitted by an apply patch tool call. + - `class BetaResponseErrorEvent` - - `id: String` + Emitted when an error occurs. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `code: String` - - `call_id: String` + The error code. - The unique ID of the apply patch tool call generated by the model. + - `message: String` - - `status: :completed | :failed` + The error message. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `param: String` - - `:completed` + The error parameter. - - `:failed` + - `sequence_number: Integer` - - `type: :apply_patch_call_output` + The sequence number of this event. - The type of the item. Always `apply_patch_call_output`. + - `type: :error` - - `:apply_patch_call_output` + The type of the event. Always `error`. + + - `:error` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. + - `class BetaResponseFileSearchCallCompletedEvent` - - `class Direct` + Emitted when a file search call is completed (results found). - - `type: :direct` + - `item_id: String` - - `:direct` + The ID of the output item that the file search call is initiated. - - `class Program` + - `output_index: Integer` - - `caller_id: String` + The index of the output item that the file search call is initiated. - The call ID of the program item that produced this tool call. + - `sequence_number: Integer` - - `type: :program` + The sequence number of this event. - - `:program` + - `type: :"response.file_search_call.completed"` - - `created_by: String` + The type of the event. Always `response.file_search_call.completed`. - The ID of the entity that created this tool call output. + - `:"response.file_search_call.completed"` - - `output: String` + - `agent: Agent{ agent_name}` - Optional textual output returned by the apply patch tool. + The agent that owns this multi-agent streaming event. - - `class McpCall` + - `agent_name: String` - An invocation of a tool on an MCP server. + The canonical name of the agent that produced this item. - - `id: String` + - `class BetaResponseFileSearchCallInProgressEvent` - The unique ID of the tool call. + Emitted when a file search call is initiated. - - `arguments: String` + - `item_id: String` - A JSON string of the arguments passed to the tool. + The ID of the output item that the file search call is initiated. - - `name: String` + - `output_index: Integer` - The name of the tool that was run. + The index of the output item that the file search call is initiated. - - `server_label: String` + - `sequence_number: Integer` - The label of the MCP server running the tool. + The sequence number of this event. - - `type: :mcp_call` + - `type: :"response.file_search_call.in_progress"` - The type of the item. Always `mcp_call`. + The type of the event. Always `response.file_search_call.in_progress`. - - `:mcp_call` + - `:"response.file_search_call.in_progress"` - `agent: Agent{ 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: 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: String` - - The error from the tool call, if any. - - - `output: String` + - `class BetaResponseFileSearchCallSearchingEvent` - The output from the tool call. + Emitted when a file search is currently searching. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `item_id: String` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The ID of the output item that the file search call is initiated. - - `:in_progress` + - `output_index: Integer` - - `:completed` + The index of the output item that the file search call is searching. - - `:incomplete` + - `sequence_number: Integer` - - `:calling` + The sequence number of this event. - - `:failed` + - `type: :"response.file_search_call.searching"` - - `class McpListTools` + The type of the event. Always `response.file_search_call.searching`. - A list of tools available on an MCP server. + - `:"response.file_search_call.searching"` - - `id: String` + - `agent: Agent{ agent_name}` - The unique ID of the list. + The agent that owns this multi-agent streaming event. - - `server_label: String` + - `agent_name: String` - The label of the MCP server. + The canonical name of the agent that produced this item. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `class BetaResponseFunctionCallArgumentsDeltaEvent` - The tools available on the server. + Emitted when there is a partial function-call arguments delta. - - `input_schema: untyped` + - `delta: String` - The JSON schema describing the tool's input. + The function-call arguments delta that is added. - - `name: String` + - `item_id: String` - The name of the tool. + The ID of the output item that the function-call arguments delta is added to. - - `annotations: untyped` + - `output_index: Integer` - Additional annotations about the tool. + The index of the output item that the function-call arguments delta is added to. - - `description: String` + - `sequence_number: Integer` - The description of the tool. + The sequence number of this event. - - `type: :mcp_list_tools` + - `type: :"response.function_call_arguments.delta"` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always `response.function_call_arguments.delta`. - - `:mcp_list_tools` + - `:"response.function_call_arguments.delta"` - `agent: Agent{ 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: String` - - Error message if the server could not list tools. - - - `class McpApprovalRequest` + - `class BetaResponseFunctionCallArgumentsDoneEvent` - A request for human approval of a tool invocation. + Emitted when function-call arguments are finalized. - - `id: String` + - `arguments: String` - The unique ID of the approval request. + The function-call arguments. - - `arguments: String` + - `item_id: String` - A JSON string of arguments for the tool. + The ID of the item. - `name: String` - The name of the tool to run. + The name of the function that was called. - - `server_label: String` + - `output_index: Integer` - The label of the MCP server making the request. + The index of the output item. - - `type: :mcp_approval_request` + - `sequence_number: Integer` - The type of the item. Always `mcp_approval_request`. + The sequence number of this event. - - `:mcp_approval_request` + - `type: :"response.function_call_arguments.done"` + + - `:"response.function_call_arguments.done"` - `agent: Agent{ 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. - - `class McpApprovalResponse` - - A response to an MCP approval request. - - - `id: String` + - `class BetaResponseInProgressEvent` - The unique ID of the approval response + Emitted when the response is in progress. - - `approval_request_id: String` + - `response: BetaResponse` - The ID of the approval request being answered. + The response that is in progress. - - `approve: bool` + - `sequence_number: Integer` - Whether the request was approved. + The sequence number of this event. - - `type: :mcp_approval_response` + - `type: :"response.in_progress"` - The type of the item. Always `mcp_approval_response`. + The type of the event. Always `response.in_progress`. - - `:mcp_approval_response` + - `:"response.in_progress"` - `agent: Agent{ 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. - - `reason: String` + - `class BetaResponseFailedEvent` - Optional reason for the decision. + An event that is emitted when a response fails. - - `class BetaResponseCustomToolCall` + - `response: BetaResponse` - A call to a custom tool created by the model. + The response that failed. - - `call_id: String` + - `sequence_number: Integer` - An identifier used to map this custom tool call to a tool call output. + The sequence number of this event. - - `input: String` + - `type: :"response.failed"` - The input for the custom tool call generated by the model. + The type of the event. Always `response.failed`. - - `name: String` + - `:"response.failed"` - The name of the custom tool being called. + - `agent: Agent{ agent_name}` - - `type: :custom_tool_call` + The agent that owns this multi-agent streaming event. - The type of the custom tool call. Always `custom_tool_call`. + - `agent_name: String` - - `:custom_tool_call` + The canonical name of the agent that produced this item. - - `id: String` + - `class BetaResponseIncompleteEvent` - The unique ID of the custom tool call in the OpenAI platform. + An event that is emitted when a response finishes as incomplete. - - `agent: Agent{ agent_name}` + - `response: BetaResponse` - The agent that produced this item. + The response that was incomplete. - - `agent_name: String` + - `sequence_number: Integer` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `type: :"response.incomplete"` - The execution context that produced this tool call. + The type of the event. Always `response.incomplete`. - - `class Direct` + - `:"response.incomplete"` - - `type: :direct` + - `agent: Agent{ agent_name}` - - `:direct` + The agent that owns this multi-agent streaming event. - - `class Program` + - `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. + - `class BetaResponseOutputItemAddedEvent` - - `type: :program` + Emitted when a new output item is added. - - `:program` + - `item: BetaResponseOutputItem` - - `namespace: String` + The output item that was added. - The namespace of the custom tool being called. + - `class BetaResponseOutputMessage` - - `class BetaResponseCustomToolCallOutputItem` + An output message from the model. - The output of a custom tool call from your code, being sent back to the model. + - `class BetaResponseFileSearchToolCall` - - `id: String` + 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 unique ID of the custom tool call output item. + - `class BetaResponseFunctionToolCall` - - `status: :in_progress | :completed | :incomplete` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaResponseFunctionToolCallOutputItem` - - `:in_progress` + - `class AgentMessage` - - `:completed` + - `class MultiAgentCall` - - `:incomplete` + - `class MultiAgentCallOutput` - - `created_by: String` + - `class BetaResponseFunctionWebSearch` - The identifier of the actor that created the item. + 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. - - `output_index: Integer` + - `class BetaResponseComputerToolCall` - The index of the output item that was added. + 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. - - `sequence_number: Integer` + - `class BetaResponseComputerToolCallOutputItem` - The sequence number of this event. + - `class BetaResponseReasoningItem` - - `type: :"response.output_item.added"` + 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 event. Always `response.output_item.added`. + - `class Program` - - `:"response.output_item.added"` + - `class ProgramOutput` - - `agent: Agent{ agent_name}` + - `class BetaResponseToolSearchCall` - The agent that owns this multi-agent streaming event. + - `class BetaResponseToolSearchOutputItem` - - `agent_name: String` + - `class AdditionalTools` - The canonical name of the agent that produced this item. + - `class BetaResponseCompactionItem` -### Beta Response Output Item Done Event + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). -- `class BetaResponseOutputItemDoneEvent` + - `class ImageGenerationCall` - Emitted when an output item is marked done. + An image generation request made by the model. - - `item: BetaResponseOutputItem` + - `class BetaResponseCodeInterpreterToolCall` - The output item that was marked done. + A tool call to run code. - - `class BetaResponseOutputMessage` + - `class LocalShellCall` - An output message from the model. + A tool call to run a command on the local shell. - - `id: String` + - `class LocalShellCallOutput` - The unique ID of the output message. + The output of a local shell tool call. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `class BetaResponseFunctionShellToolCall` - The content of the output message. + A tool call that executes one or more shell commands in a managed environment. - - `class BetaResponseOutputText` + - `class BetaResponseFunctionShellToolCallOutput` - A text output from the model. + The output of a shell tool call that was emitted. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `class BetaResponseApplyPatchToolCall` - The annotations of the text output. + A tool call that applies file diffs by creating, deleting, or updating files. - - `class FileCitation` + - `class BetaResponseApplyPatchToolCallOutput` - A citation to a file. + The output emitted by an apply patch tool call. - - `file_id: String` + - `class McpCall` - The ID of the file. + An invocation of a tool on an MCP server. - - `filename: String` + - `class McpListTools` - The filename of the file cited. + A list of tools available on an MCP server. - - `index: Integer` + - `class McpApprovalRequest` - The index of the file in the list of files. + A request for human approval of a tool invocation. - - `type: :file_citation` + - `class McpApprovalResponse` - The type of the file citation. Always `file_citation`. + A response to an MCP approval request. - - `:file_citation` + - `class BetaResponseCustomToolCall` - - `class URLCitation` + A call to a custom tool created by the model. - A citation for a web resource used to generate a model response. + - `class BetaResponseCustomToolCallOutputItem` - - `end_index: Integer` + The output of a custom tool call from your code, being sent back to the model. - The index of the last character of the URL citation in the message. + - `output_index: Integer` - - `start_index: Integer` + The index of the output item that was added. - The index of the first character of the URL citation in the message. + - `sequence_number: Integer` - - `title: String` + The sequence number of this event. - The title of the web resource. + - `type: :"response.output_item.added"` - - `type: :url_citation` + The type of the event. Always `response.output_item.added`. - The type of the URL citation. Always `url_citation`. + - `:"response.output_item.added"` - - `:url_citation` + - `agent: Agent{ agent_name}` - - `url: String` + The agent that owns this multi-agent streaming event. - The URL of the web resource. + - `agent_name: String` - - `class ContainerFileCitation` + The canonical name of the agent that produced this item. - A citation for a container file used to generate a model response. + - `class BetaResponseOutputItemDoneEvent` - - `container_id: String` + Emitted when an output item is marked done. - The ID of the container file. + - `item: BetaResponseOutputItem` - - `end_index: Integer` + The output item that was marked done. - The index of the last character of the container file citation in the message. + - `output_index: Integer` - - `file_id: String` + The index of the output item that was marked done. - The ID of the file. + - `sequence_number: Integer` - - `filename: String` + The sequence number of this event. - The filename of the container file cited. + - `type: :"response.output_item.done"` - - `start_index: Integer` + The type of the event. Always `response.output_item.done`. - The index of the first character of the container file citation in the message. + - `:"response.output_item.done"` - - `type: :container_file_citation` + - `agent: Agent{ agent_name}` - The type of the container file citation. Always `container_file_citation`. + The agent that owns this multi-agent streaming event. - - `:container_file_citation` + - `agent_name: String` - - `class FilePath` + The canonical name of the agent that produced this item. - A path to a file. + - `class BetaResponseReasoningSummaryPartAddedEvent` - - `file_id: String` + Emitted when a new reasoning summary part is added. - The ID of the file. + - `item_id: String` - - `index: Integer` + The ID of the item this summary part is associated with. - The index of the file in the list of files. + - `output_index: Integer` - - `type: :file_path` + The index of the output item this summary part is associated with. - The type of the file path. Always `file_path`. + - `part: Part{ text, type}` - - `:file_path` + The summary part that was added. - `text: String` - The text output from the model. + The text of the summary part. - - `type: :output_text` + - `type: :summary_text` - The type of the output text. Always `output_text`. + The type of the summary part. Always `summary_text`. - - `:output_text` + - `:summary_text` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `sequence_number: Integer` - - `token: String` + The sequence number of this event. - - `bytes: Array[Integer]` + - `summary_index: Integer` - - `logprob: Float` + The index of the summary part within the reasoning summary. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `type: :"response.reasoning_summary_part.added"` - - `token: String` + The type of the event. Always `response.reasoning_summary_part.added`. - - `bytes: Array[Integer]` + - `:"response.reasoning_summary_part.added"` - - `logprob: Float` + - `agent: Agent{ agent_name}` - - `class BetaResponseOutputRefusal` + The agent that owns this multi-agent streaming event. - 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. + - `class BetaResponseReasoningSummaryPartDoneEvent` - - `type: :refusal` + Emitted when a reasoning summary part is completed. - The type of the refusal. Always `refusal`. + - `item_id: String` - - `:refusal` + The ID of the item this summary part is associated with. - - `role: :assistant` + - `output_index: Integer` - The role of the output message. Always `assistant`. + The index of the output item this summary part is associated with. - - `:assistant` + - `part: Part{ text, type}` - - `status: :in_progress | :completed | :incomplete` + The completed summary part. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `text: String` - - `:in_progress` + The text of the summary part. - - `:completed` + - `type: :summary_text` - - `:incomplete` + The type of the summary part. Always `summary_text`. - - `type: :message` + - `:summary_text` - The type of the output message. Always `message`. + - `sequence_number: Integer` - - `:message` + The sequence number of this event. + + - `summary_index: Integer` + + 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: Agent{ 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. - - `phase: :commentary` - - 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. + - `status: :incomplete` - - `:commentary` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `class BetaResponseFileSearchToolCall` + - `:incomplete` - 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. + - `class BetaResponseReasoningSummaryTextDeltaEvent` - - `id: String` + Emitted when a delta is added to a reasoning summary text. - The unique ID of the file search tool call. + - `delta: String` - - `queries: Array[String]` + The text delta that was added to the summary. - The queries used to search for files. + - `item_id: String` - - `status: :in_progress | :searching | :completed | 2 more` + The ID of the item this summary text delta is associated with. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `output_index: Integer` - - `:in_progress` + The index of the output item this summary text delta is associated with. - - `:searching` + - `sequence_number: Integer` - - `:completed` + The sequence number of this event. - - `:incomplete` + - `summary_index: Integer` - - `:failed` + The index of the summary part within the reasoning summary. - - `type: :file_search_call` + - `type: :"response.reasoning_summary_text.delta"` - The type of the file search tool call. Always `file_search_call`. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `:file_search_call` + - `:"response.reasoning_summary_text.delta"` - `agent: Agent{ 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. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - The results of the file search tool call. + - `class BetaResponseReasoningSummaryTextDoneEvent` - - `attributes: Hash[Symbol, String | Float | bool]` + Emitted when a reasoning summary text 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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `item_id: String` - - `String = String` + The ID of the item this summary text is associated with. - - `Float = Float` + - `output_index: Integer` - - `UnionMember2 = bool` + The index of the output item this summary text is associated with. - - `file_id: String` + - `sequence_number: Integer` - The unique ID of the file. + The sequence number of this event. - - `filename: String` + - `summary_index: Integer` - The name of the file. + The index of the summary part within the reasoning summary. - - `score: Float` + - `text: String` - The relevance score of the file - a value between 0 and 1. + The full text of the completed reasoning summary. - - `text: String` + - `type: :"response.reasoning_summary_text.done"` - The text that was retrieved from the file. + The type of the event. Always `response.reasoning_summary_text.done`. - - `class BetaResponseFunctionToolCall` + - `:"response.reasoning_summary_text.done"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `agent: Agent{ agent_name}` - - `arguments: String` + The agent that owns this multi-agent streaming event. - A JSON string of the arguments to pass to the function. + - `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. + - `class BetaResponseReasoningTextDeltaEvent` - - `name: String` + Emitted when a delta is added to a reasoning text. - The name of the function to run. + - `content_index: Integer` - - `type: :function_call` + The index of the reasoning content part this delta is associated with. - The type of the function tool call. Always `function_call`. + - `delta: String` - - `:function_call` + The text delta that was added to the reasoning content. - - `id: String` + - `item_id: String` - The unique ID of the function tool call. + The ID of the item this reasoning text delta is associated with. - - `agent: Agent{ agent_name}` + - `output_index: Integer` - The agent that produced this item. + The index of the output item this reasoning text delta is associated with. - - `agent_name: String` + - `sequence_number: Integer` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `type: :"response.reasoning_text.delta"` - The execution context that produced this tool call. + The type of the event. Always `response.reasoning_text.delta`. - - `class Direct` + - `:"response.reasoning_text.delta"` - - `type: :direct` + - `agent: Agent{ agent_name}` - - `:direct` + The agent that owns this multi-agent streaming event. - - `class Program` + - `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. + - `class BetaResponseReasoningTextDoneEvent` - - `type: :program` + Emitted when a reasoning text is completed. - - `:program` + - `content_index: Integer` - - `namespace: String` + The index of the reasoning content part. - The namespace of the function to run. + - `item_id: String` - - `status: :in_progress | :completed | :incomplete` + The ID of the item this reasoning text is associated with. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_index: Integer` - - `:in_progress` + The index of the output item this reasoning text is associated with. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of this event. - - `class BetaResponseFunctionToolCallOutputItem` + - `text: String` - - `id: String` + The full text of the completed reasoning content. - The unique ID of the function call tool output. + - `type: :"response.reasoning_text.done"` - - `call_id: String` + The type of the event. Always `response.reasoning_text.done`. - The unique ID of the function tool call generated by the model. + - `:"response.reasoning_text.done"` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `agent: Agent{ agent_name}` - The output from the function call generated by your code. - Can be a string or an list of output content. + The agent that owns this multi-agent streaming event. - - `String = String` + - `agent_name: String` - A string of the output of the function call. + The canonical name of the agent that produced this item. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class BetaResponseRefusalDeltaEvent` - Text, image, or file output of the function call. + Emitted when there is a partial refusal text. - - `class BetaResponseInputText` + - `content_index: Integer` - A text input to the model. + The index of the content part that the refusal text is added to. - - `text: String` + - `delta: String` - The text input to the model. + The refusal text that is added. - - `type: :input_text` + - `item_id: String` - The type of the input item. Always `input_text`. + The ID of the output item that the refusal text is added to. - - `:input_text` + - `output_index: Integer` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The index of the output item that the refusal text is added to. - Marks the exact end of a reusable 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: Integer` - - `mode: :explicit` + The sequence number of this event. - The breakpoint mode. Always `explicit`. + - `type: :"response.refusal.delta"` - - `:explicit` + The type of the event. Always `response.refusal.delta`. - - `class BetaResponseInputImage` + - `:"response.refusal.delta"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent: Agent{ agent_name}` - - `detail: :low | :high | :auto | :original` + The agent that owns this multi-agent streaming event. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `agent_name: String` - - `:low` + The canonical name of the agent that produced this item. - - `:high` + - `class BetaResponseRefusalDoneEvent` - - `:auto` + Emitted when refusal text is finalized. - - `:original` + - `content_index: Integer` - - `type: :input_image` + The index of the content part that the refusal text is finalized. - The type of the input item. Always `input_image`. + - `item_id: String` - - `:input_image` + The ID of the output item that the refusal text is finalized. - - `file_id: String` + - `output_index: Integer` - The ID of the file to be sent to the model. + The index of the output item that the refusal text is finalized. - - `image_url: String` + - `refusal: 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 refusal text that is finalized. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `sequence_number: Integer` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The sequence number of this event. - - `mode: :explicit` + - `type: :"response.refusal.done"` - The breakpoint mode. Always `explicit`. + The type of the event. Always `response.refusal.done`. - - `:explicit` + - `:"response.refusal.done"` - - `class BetaResponseInputFile` + - `agent: Agent{ agent_name}` - A file input to the model. + The agent that owns this multi-agent streaming event. - - `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` + - `class BetaResponseTextDeltaEvent` - - `detail: :auto | :low | :high` + Emitted when there is an additional text delta. - 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`. + - `content_index: Integer` - - `:auto` + The index of the content part that the text delta was added to. - - `:low` + - `delta: String` - - `:high` + The text delta that was added. - - `file_data: String` + - `item_id: String` - The content of the file to be sent to the model. + The ID of the output item that the text delta was added to. - - `file_id: String` + - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` - The ID of the file to be sent to the model. + The log probabilities of the tokens in the delta. - - `file_url: String` + - `token: String` - The URL of the file to be sent to the model. + A possible text token. - - `filename: String` + - `logprob: Float` - The name of the file to be sent to the model. + The log probability of this token. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `top_logprobs: Array[TopLogprob{ token, logprob}]` - Marks the exact end of a reusable 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 log probabilities of up to 20 of the most likely tokens. - - `mode: :explicit` + - `token: String` - The breakpoint mode. Always `explicit`. + A possible text token. - - `:explicit` + - `logprob: Float` - - `status: :in_progress | :completed | :incomplete` + The log probability of this token. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_index: Integer` - - `:in_progress` + The index of the output item that the text delta was added to. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number for this event. - - `type: :function_call_output` + - `type: :"response.output_text.delta"` - The type of the function tool call output. Always `function_call_output`. + The type of the event. Always `response.output_text.delta`. - - `:function_call_output` + - `:"response.output_text.delta"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` + - `class BetaResponseTextDoneEvent` - - `type: :direct` + Emitted when text content is finalized. - The caller type. Always `direct`. + - `content_index: Integer` - - `:direct` + The index of the content part that the text content is finalized. - - `class Program` + - `item_id: String` - - `caller_id: String` + The ID of the output item that the text content is finalized. - The call ID of the program item that produced this tool call. + - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` - - `type: :program` + The log probabilities of the tokens in the delta. - The caller type. Always `program`. + - `token: String` - - `:program` + A possible text token. - - `created_by: String` + - `logprob: Float` - The identifier of the actor that created the item. + The log probability of this token. - - `class AgentMessage` + - `top_logprobs: Array[TopLogprob{ token, logprob}]` - - `id: String` + The log probabilities of up to 20 of the most likely tokens. - The unique ID of the agent message. + - `token: String` - - `author: String` + A possible text token. - The sending agent identity. + - `logprob: Float` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + The log probability of this token. - Encrypted content sent between agents. + - `output_index: Integer` - - `class BetaResponseInputText` + The index of the output item that the text content is finalized. - A text input to the model. + - `sequence_number: Integer` - - `class BetaResponseOutputText` + The sequence number for this event. - A text output from the model. + - `text: String` - - `class Text` + The text content that is finalized. - A text content. + - `type: :"response.output_text.done"` - - `text: String` + The type of the event. Always `response.output_text.done`. - - `type: :text` + - `:"response.output_text.done"` - - `:text` + - `agent: Agent{ agent_name}` - - `class SummaryText` + The agent that owns this multi-agent streaming event. - A summary text from the model. + - `agent_name: String` - - `text: String` + The canonical name of the agent that produced this item. - A summary of the reasoning output from the model so far. + - `class BetaResponseWebSearchCallCompletedEvent` - - `type: :summary_text` + Emitted when a web search call is completed. - The type of the object. Always `summary_text`. + - `item_id: String` - - `:summary_text` + Unique ID for the output item associated with the web search call. - - `class ReasoningText` + - `output_index: Integer` - Reasoning text from the model. + The index of the output item that the web search call is associated with. - - `text: String` + - `sequence_number: Integer` - The reasoning text from the model. + The sequence number of the web search call being processed. - - `type: :reasoning_text` + - `type: :"response.web_search_call.completed"` - The type of the reasoning text. Always `reasoning_text`. + The type of the event. Always `response.web_search_call.completed`. - - `:reasoning_text` + - `:"response.web_search_call.completed"` - - `class BetaResponseOutputRefusal` + - `agent: Agent{ agent_name}` - A refusal from the model. + The agent that owns this multi-agent streaming event. - - `class BetaResponseInputImage` + - `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. - - `class ComputerScreenshot` + - `class BetaResponseWebSearchCallInProgressEvent` - A screenshot of a computer. + Emitted when a web search call is initiated. - - `detail: :low | :high | :auto | :original` + - `item_id: String` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Unique ID for the output item associated with the web search call. - - `:low` + - `output_index: Integer` - - `:high` + The index of the output item that the web search call is associated with. - - `:auto` + - `sequence_number: Integer` - - `:original` + The sequence number of the web search call being processed. - - `file_id: String` + - `type: :"response.web_search_call.in_progress"` - The identifier of an uploaded file that contains the screenshot. + The type of the event. Always `response.web_search_call.in_progress`. - - `image_url: String` + - `:"response.web_search_call.in_progress"` - The URL of the screenshot image. + - `agent: Agent{ agent_name}` - - `type: :computer_screenshot` + The agent that owns this multi-agent streaming event. - 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: PromptCacheBreakpoint{ mode}` + - `class BetaResponseWebSearchCallSearchingEvent` - Marks the exact end of a reusable 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 a web search call is executing. - - `mode: :explicit` + - `item_id: String` - The breakpoint mode. Always `explicit`. + Unique ID for the output item associated with the web search call. - - `:explicit` + - `output_index: Integer` - - `class BetaResponseInputFile` + The index of the output item that the web search call is associated with. - A file input to the model. + - `sequence_number: Integer` - - `class EncryptedContent` + The sequence number of the web search call being processed. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `type: :"response.web_search_call.searching"` - - `encrypted_content: String` + The type of the event. Always `response.web_search_call.searching`. - Opaque encrypted content. + - `:"response.web_search_call.searching"` - - `type: :encrypted_content` + - `agent: Agent{ agent_name}` - The type of the input item. Always `encrypted_content`. + The agent that owns this multi-agent streaming event. - - `:encrypted_content` + - `agent_name: String` - - `recipient: String` + The canonical name of the agent that produced this item. - The destination agent identity. + - `class BetaResponseImageGenCallCompletedEvent` - - `type: :agent_message` + Emitted when an image generation tool call has completed and the final image is available. - The type of the item. Always `agent_message`. + - `item_id: String` - - `:agent_message` + The unique identifier of the image generation item being processed. - - `agent: Agent{ agent_name}` + - `output_index: Integer` - The agent that produced this item. + The index of the output item in the response's output array. - - `agent_name: String` + - `sequence_number: Integer` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `class MultiAgentCall` + - `type: :"response.image_generation_call.completed"` - - `id: String` + The type of the event. Always 'response.image_generation_call.completed'. - The unique ID of the multi-agent call item. + - `:"response.image_generation_call.completed"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `agent: Agent{ agent_name}` - The multi-agent action to execute. + The agent that owns this multi-agent streaming event. - - `:spawn_agent` + - `agent_name: String` - - `:interrupt_agent` + The canonical name of the agent that produced this item. - - `:list_agents` + - `class BetaResponseImageGenCallGeneratingEvent` - - `:send_message` + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `:followup_task` + - `item_id: String` - - `:wait_agent` + The unique identifier of the image generation item being processed. - - `arguments: String` + - `output_index: Integer` - The JSON string of arguments generated for the action. + The index of the output item in the response's output array. - - `call_id: String` + - `sequence_number: Integer` - The unique ID linking this call to its output. + The sequence number of the image generation item being processed. - - `type: :multi_agent_call` + - `type: :"response.image_generation_call.generating"` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the event. Always 'response.image_generation_call.generating'. - - `:multi_agent_call` + - `:"response.image_generation_call.generating"` - `agent: Agent{ 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. - - `class MultiAgentCallOutput` + - `class BetaResponseImageGenCallInProgressEvent` - - `id: String` + Emitted when an image generation tool call is in progress. - The unique ID of the multi-agent call output item. + - `item_id: String` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The unique identifier of the image generation item being processed. - The multi-agent action that produced this result. + - `output_index: Integer` - - `:spawn_agent` + The index of the output item in the response's output array. - - `:interrupt_agent` + - `sequence_number: Integer` - - `:list_agents` + The sequence number of the image generation item being processed. - - `:send_message` + - `type: :"response.image_generation_call.in_progress"` - - `:followup_task` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `:wait_agent` + - `:"response.image_generation_call.in_progress"` - - `call_id: String` + - `agent: Agent{ agent_name}` - The unique ID of the multi-agent call. + The agent that owns this multi-agent streaming event. - - `output: Array[BetaResponseOutputText]` + - `agent_name: String` - Text output returned by the multi-agent action. + The canonical name of the agent that produced this item. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `class BetaResponseImageGenCallPartialImageEvent` - The annotations of the text output. + Emitted when a partial image is available during image generation streaming. - - `text: String` + - `item_id: String` - The text output from the model. + The unique identifier of the image generation item being processed. - - `type: :output_text` + - `output_index: Integer` - The type of the output text. Always `output_text`. + The index of the output item in the response's output array. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `partial_image_b64: String` - - `type: :multi_agent_call_output` + Base64-encoded partial image data, suitable for rendering as an image. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `partial_image_index: Integer` - - `:multi_agent_call_output` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + + - `sequence_number: Integer` + + The sequence number of the image generation item being processed. + + - `type: :"response.image_generation_call.partial_image"` + + The type of the event. Always 'response.image_generation_call.partial_image'. + + - `:"response.image_generation_call.partial_image"` - `agent: Agent{ 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. - - `class BetaResponseFunctionWebSearch` - - 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` + - `class BetaResponseMcpCallArgumentsDeltaEvent` - The unique ID of the web search tool call. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `delta: String` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A JSON string containing the partial update to the arguments for the MCP tool call. - - `class Search` + - `item_id: String` - Action type "search" - Performs a web search query. + The unique identifier of the MCP tool call item being processed. - - `type: :search` + - `output_index: Integer` - The action type. + The index of the output item in the response's output array. - - `:search` + - `sequence_number: Integer` - - `queries: Array[String]` + The sequence number of this event. - The search queries. + - `type: :"response.mcp_call_arguments.delta"` - - `query: String` + The type of the event. Always 'response.mcp_call_arguments.delta'. - The search query. + - `:"response.mcp_call_arguments.delta"` - - `sources: Array[Source{ type, url}]` + - `agent: Agent{ agent_name}` - The sources used in the search. + The agent that owns this multi-agent streaming event. - - `type: :url` + - `agent_name: String` - The type of source. Always `url`. + The canonical name of the agent that produced this item. - - `:url` + - `class BetaResponseMcpCallArgumentsDoneEvent` - - `url: String` + Emitted when the arguments for an MCP tool call are finalized. - The URL of the source. + - `arguments: String` - - `class OpenPage` + A JSON string containing the finalized arguments for the MCP tool call. - Action type "open_page" - Opens a specific URL from search results. + - `item_id: String` - - `type: :open_page` + The unique identifier of the MCP tool call item being processed. - The action type. + - `output_index: Integer` - - `:open_page` + The index of the output item in the response's output array. - - `url: String` + - `sequence_number: Integer` - The URL opened by the model. + The sequence number of this event. - - `class FindInPage` + - `type: :"response.mcp_call_arguments.done"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the event. Always 'response.mcp_call_arguments.done'. - - `pattern: String` + - `:"response.mcp_call_arguments.done"` - The pattern or text to search for within the page. + - `agent: Agent{ agent_name}` - - `type: :find_in_page` + The agent that owns this multi-agent streaming event. - The action type. + - `agent_name: String` - - `:find_in_page` + The canonical name of the agent that produced this item. - - `url: String` + - `class BetaResponseMcpCallCompletedEvent` - The URL of the page searched for the pattern. + Emitted when an MCP tool call has completed successfully. - - `status: :in_progress | :searching | :completed | :failed` + - `item_id: String` - The status of the web search tool call. + The ID of the MCP tool call item that completed. - - `:in_progress` + - `output_index: Integer` - - `:searching` + The index of the output item that completed. - - `:completed` + - `sequence_number: Integer` - - `:failed` + The sequence number of this event. - - `type: :web_search_call` + - `type: :"response.mcp_call.completed"` - The type of the web search tool call. Always `web_search_call`. + The type of the event. Always 'response.mcp_call.completed'. - - `:web_search_call` + - `:"response.mcp_call.completed"` - `agent: Agent{ 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. - - `class BetaResponseComputerToolCall` + - `class BetaResponseMcpCallFailedEvent` - 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. + Emitted when an MCP tool call has failed. - - `id: String` + - `item_id: String` - The unique ID of the computer call. + The ID of the MCP tool call item that failed. - - `call_id: String` + - `output_index: Integer` - An identifier used when responding to the tool call with output. + The index of the output item that failed. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `sequence_number: Integer` - The pending safety checks for the computer call. + The sequence number of this event. - - `id: String` + - `type: :"response.mcp_call.failed"` - The ID of the pending safety check. + The type of the event. Always 'response.mcp_call.failed'. - - `code: String` + - `:"response.mcp_call.failed"` - The type of the pending safety check. + - `agent: Agent{ agent_name}` - - `message: String` + The agent that owns this multi-agent streaming event. - Details about the pending safety check. + - `agent_name: String` - - `status: :in_progress | :completed | :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. + - `class BetaResponseMcpCallInProgressEvent` - - `:in_progress` + Emitted when an MCP tool call is in progress. - - `:completed` + - `item_id: String` - - `:incomplete` + The unique identifier of the MCP tool call item being processed. - - `type: :computer_call` + - `output_index: Integer` - The type of the computer call. Always `computer_call`. + The index of the output item in the response's output array. - - `:computer_call` + - `sequence_number: Integer` - - `action: BetaComputerAction` + The sequence number of this event. - A click action. + - `type: :"response.mcp_call.in_progress"` - - `class Click` + The type of the event. Always 'response.mcp_call.in_progress'. - A click action. + - `:"response.mcp_call.in_progress"` - - `button: :left | :right | :wheel | 2 more` + - `agent: Agent{ 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` + - `class BetaResponseMcpListToolsCompletedEvent` - - `:back` + Emitted when the list of available MCP tools has been successfully retrieved. - - `:forward` + - `item_id: String` - - `type: :click` + The ID of the MCP tool call item that produced this output. - Specifies the event type. For a click action, this property is always `click`. + - `output_index: Integer` - - `:click` + The index of the output item that was processed. - - `x: Integer` + - `sequence_number: Integer` - The x-coordinate where the click occurred. + The sequence number of this event. - - `y_: Integer` + - `type: :"response.mcp_list_tools.completed"` - The y-coordinate where the click occurred. + The type of the event. Always 'response.mcp_list_tools.completed'. - - `keys: Array[String]` + - `:"response.mcp_list_tools.completed"` - The keys being held while clicking. + - `agent: Agent{ agent_name}` - - `class DoubleClick` + The agent that owns this multi-agent streaming event. - A double click action. + - `agent_name: String` - - `keys: Array[String]` + The canonical name of the agent that produced this item. - The keys being held while double-clicking. + - `class BetaResponseMcpListToolsFailedEvent` - - `type: :double_click` + Emitted when the attempt to list available MCP tools has failed. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `item_id: String` - - `:double_click` + The ID of the MCP tool call item that failed. - - `x: Integer` + - `output_index: Integer` - The x-coordinate where the double click occurred. + The index of the output item that failed. - - `y_: Integer` + - `sequence_number: Integer` - The y-coordinate where the double click occurred. + The sequence number of this event. - - `class Drag` + - `type: :"response.mcp_list_tools.failed"` - A drag action. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `path: Array[Path{ x, y_}]` + - `:"response.mcp_list_tools.failed"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `agent: Agent{ agent_name}` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The agent that owns this multi-agent streaming event. - - `x: Integer` + - `agent_name: String` - The x-coordinate. + The canonical name of the agent that produced this item. - - `y_: Integer` + - `class BetaResponseMcpListToolsInProgressEvent` - The y-coordinate. + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `type: :drag` + - `item_id: String` - Specifies the event type. For a drag action, this property is always set to `drag`. + The ID of the MCP tool call item that is being processed. - - `:drag` + - `output_index: Integer` - - `keys: Array[String]` + The index of the output item that is being processed. - The keys being held while dragging the mouse. + - `sequence_number: Integer` - - `class Keypress` + The sequence number of this event. - A collection of keypresses the model would like to perform. + - `type: :"response.mcp_list_tools.in_progress"` - - `keys: Array[String]` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `:"response.mcp_list_tools.in_progress"` - - `type: :keypress` + - `agent: Agent{ agent_name}` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The agent that owns this multi-agent streaming event. - - `:keypress` + - `agent_name: String` - - `class Move` + The canonical name of the agent that produced this item. - A mouse move action. + - `class BetaResponseOutputTextAnnotationAddedEvent` - - `type: :move` + Emitted when an annotation is added to output text content. - Specifies the event type. For a move action, this property is always set to `move`. + - `annotation: untyped` - - `:move` + The annotation object being added. (See annotation schema for details.) - - `x: Integer` + - `annotation_index: Integer` - The x-coordinate to move to. + The index of the annotation within the content part. - - `y_: Integer` + - `content_index: Integer` - The y-coordinate to move to. + The index of the content part within the output item. - - `keys: Array[String]` + - `item_id: String` - The keys being held while moving the mouse. + The unique identifier of the item to which the annotation is being added. - - `class Screenshot` + - `output_index: Integer` - A screenshot action. + The index of the output item in the response's output array. - - `type: :screenshot` + - `sequence_number: Integer` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The sequence number of this event. - - `:screenshot` + - `type: :"response.output_text.annotation.added"` - - `class Scroll` + The type of the event. Always 'response.output_text.annotation.added'. - A scroll action. + - `:"response.output_text.annotation.added"` - - `scroll_x: Integer` + - `agent: Agent{ agent_name}` - The horizontal scroll distance. + The agent that owns this multi-agent streaming event. - - `scroll_y: Integer` + - `agent_name: String` - The vertical scroll distance. + The canonical name of the agent that produced this item. - - `type: :scroll` + - `class BetaResponseQueuedEvent` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Emitted when a response is queued and waiting to be processed. - - `:scroll` + - `response: BetaResponse` - - `x: Integer` + The full response object that is queued. - The x-coordinate where the scroll occurred. + - `sequence_number: Integer` - - `y_: Integer` + The sequence number for this event. - The y-coordinate where the scroll occurred. + - `type: :"response.queued"` - - `keys: Array[String]` + The type of the event. Always 'response.queued'. - The keys being held while scrolling. + - `:"response.queued"` - - `class Type` + - `agent: Agent{ agent_name}` - An action to type in text. + The agent that owns this multi-agent streaming event. - - `text: String` + - `agent_name: String` - The text to type. + The canonical name of the agent that produced this item. - - `type: :type` + - `class BetaResponseCustomToolCallInputDeltaEvent` - Specifies the event type. For a type action, this property is always set to `type`. + Event representing a delta (partial update) to the input of a custom tool call. - - `:type` + - `delta: String` - - `class Wait` + The incremental input data (delta) for the custom tool call. - A wait action. + - `item_id: String` - - `type: :wait` + Unique identifier for the API item associated with this event. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `output_index: Integer` - - `:wait` + The index of the output this delta applies to. - - `actions: BetaComputerActionList` + - `sequence_number: Integer` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The sequence number of this event. - - `class Click` + - `type: :"response.custom_tool_call_input.delta"` - A click action. + The event type identifier. - - `class DoubleClick` + - `:"response.custom_tool_call_input.delta"` - A double click action. + - `agent: Agent{ agent_name}` - - `class Drag` + The agent that owns this multi-agent streaming event. - A drag action. + - `agent_name: String` - - `class Keypress` + The canonical name of the agent that produced this item. - A collection of keypresses the model would like to perform. + - `class BetaResponseCustomToolCallInputDoneEvent` - - `class Move` + Event indicating that input for a custom tool call is complete. - A mouse move action. + - `input: String` - - `class Screenshot` + The complete input data for the custom tool call. - A screenshot action. + - `item_id: String` - - `class Scroll` + Unique identifier for the API item associated with this event. - A scroll action. + - `output_index: Integer` - - `class Type` + The index of the output this event applies to. - An action to type in text. + - `sequence_number: Integer` - - `class Wait` + The sequence number of this event. - A wait action. + - `type: :"response.custom_tool_call_input.done"` + + The event type identifier. + + - `:"response.custom_tool_call_input.done"` - `agent: Agent{ 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. - - `class BetaResponseComputerToolCallOutputItem` - - - `id: String` +### Beta Response Text Config - The unique ID of the computer call tool output. +- `class BetaResponseTextConfig` - - `call_id: String` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The ID of the computer tool call that produced the output. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `format_: BetaResponseFormatTextConfig` - A computer screenshot image used with the computer use tool. + An object specifying the format that the model must output. - - `type: :computer_screenshot` + 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). - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The default format is `{ "type": "text" }` with no additional options. - - `:computer_screenshot` + **Not recommended for gpt-4o and newer models:** - - `file_id: 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 identifier of an uploaded file that contains the screenshot. + - `class Text` - - `image_url: String` + Default response format. Used to generate text responses. - The URL of the screenshot image. + - `type: :text` - - `status: :completed | :incomplete | :failed | :in_progress` + The type of response format being defined. Always `text`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `:text` - - `:completed` + - `class BetaResponseFormatTextJSONSchemaConfig` - - `:incomplete` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:failed` + - `name: String` - - `:in_progress` + 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: :computer_call_output` + - `schema: Hash[Symbol, untyped]` - The type of the computer tool call output. Always `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/). - - `:computer_call_output` + - `type: :json_schema` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + The type of response format being defined. Always `json_schema`. - The safety checks reported by the API that have been acknowledged by the - developer. + - `:json_schema` - - `id: String` + - `description: String` - The ID of the pending safety check. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `code: String` + - `strict: bool` - The type of the pending safety check. + 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). - - `message: String` + - `class JSONObject` - Details about the pending safety check. + 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: Agent{ agent_name}` + - `type: :json_object` - The agent that produced this item. + The type of response format being defined. Always `json_object`. - - `agent_name: String` + - `:json_object` - The canonical name of the agent that produced this item. + - `verbosity: :low | :medium | :high` - - `created_by: 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 identifier of the actor that created the item. + - `:low` - - `class BetaResponseReasoningItem` + - `:medium` - 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). + - `:high` - - `id: String` +### Beta Response Text Delta Event - The unique identifier of the reasoning content. +- `class BetaResponseTextDeltaEvent` - - `summary: Array[Summary{ text, type}]` + Emitted when there is an additional text delta. - Reasoning summary content. + - `content_index: Integer` - - `text: String` + The index of the content part that the text delta was added to. - A summary of the reasoning output from the model so far. + - `delta: String` - - `type: :summary_text` + The text delta that was added. - The type of the object. Always `summary_text`. + - `item_id: String` - - `:summary_text` + The ID of the output item that the text delta was added to. - - `type: :reasoning` + - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` - The type of the object. Always `reasoning`. + The log probabilities of the tokens in the delta. - - `:reasoning` + - `token: String` - - `agent: Agent{ agent_name}` + A possible text token. - The agent that produced this item. + - `logprob: Float` - - `agent_name: String` + The log probability of this token. - The canonical name of the agent that produced this item. + - `top_logprobs: Array[TopLogprob{ token, logprob}]` - - `content: Array[Content{ text, type}]` + The log probabilities of up to 20 of the most likely tokens. - Reasoning text content. + - `token: String` - - `text: String` + A possible text token. - The reasoning text from the model. + - `logprob: Float` - - `type: :reasoning_text` + The log probability of this token. - The type of the reasoning text. Always `reasoning_text`. + - `output_index: Integer` - - `:reasoning_text` + The index of the output item that the text delta was added to. - - `encrypted_content: String` + - `sequence_number: Integer` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The sequence number for this event. - - `status: :in_progress | :completed | :incomplete` + - `type: :"response.output_text.delta"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the event. Always `response.output_text.delta`. - - `:in_progress` + - `:"response.output_text.delta"` - - `:completed` + - `agent: Agent{ agent_name}` - - `:incomplete` + The agent that owns this multi-agent streaming event. - - `class Program` + - `agent_name: String` - - `id: String` + The canonical name of the agent that produced this item. - The unique ID of the program item. +### Beta Response Text Done Event - - `call_id: String` +- `class BetaResponseTextDoneEvent` - The stable call ID of the program item. + Emitted when text content is finalized. - - `code: String` + - `content_index: Integer` - The JavaScript source executed by programmatic tool calling. + The index of the content part that the text content is finalized. - - `fingerprint: String` + - `item_id: String` - Opaque program replay fingerprint that must be round-tripped. + The ID of the output item that the text content is finalized. - - `type: :program` + - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` - The type of the item. Always `program`. + The log probabilities of the tokens in the delta. - - `:program` + - `token: String` - - `agent: Agent{ agent_name}` + A possible text token. - The agent that produced this item. + - `logprob: Float` - - `agent_name: String` + The log probability of this token. - The canonical name of the agent that produced this item. + - `top_logprobs: Array[TopLogprob{ token, logprob}]` - - `class ProgramOutput` + The log probabilities of up to 20 of the most likely tokens. - - `id: String` + - `token: String` - The unique ID of the program output item. + A possible text token. - - `call_id: String` + - `logprob: Float` - The call ID of the program item. + The log probability of this token. - - `result: String` + - `output_index: Integer` - The result produced by the program item. + The index of the output item that the text content is finalized. - - `status: :completed | :incomplete` + - `sequence_number: Integer` - The terminal status of the program output item. + The sequence number for this event. - - `:completed` + - `text: String` - - `:incomplete` + The text content that is finalized. - - `type: :program_output` + - `type: :"response.output_text.done"` - The type of the item. Always `program_output`. + The type of the event. Always `response.output_text.done`. - - `:program_output` + - `:"response.output_text.done"` - `agent: Agent{ 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. - - `class BetaResponseToolSearchCall` +### Beta Response Tool Search Call + +- `class BetaResponseToolSearchCall` - `id: String` @@ -114463,7 +126654,9 @@ puts(beta_compacted_response) The identifier of the actor that created the item. - - `class BetaResponseToolSearchOutputItem` +### Beta Response Tool Search Output Item + +- `class BetaResponseToolSearchOutputItem` - `id: String` @@ -114592,7 +126785,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -114602,7 +126795,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -114649,7 +126846,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -114659,7 +126856,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -115599,1641 +127800,1386 @@ puts(beta_compacted_response) The identifier of the actor that created the item. - - `class AdditionalTools` - - - `id: String` - - The unique ID of the additional tools item. - - - `role: :unknown | :user | :assistant | 5 more` - - The role that provided the additional tools. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` +### Beta Response Tool Search Output Item Param - - `:tool` +- `class BetaResponseToolSearchOutputItemParam` - `tools: Array[BetaTool]` - The additional tool definitions made available at this item. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool` 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). - - `class BetaFileSearchTool` - - 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). - - - `class BetaComputerTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool` - - 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). - - - `class Mcp` - - 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). - - - `class CodeInterpreter` - - A tool that runs Python code to help generate a response to a prompt. - - - `class ProgrammaticToolCalling` - - - `class ImageGeneration` - - A tool that generates images using the GPT image models. - - - `class LocalShell` - - A tool that allows the model to execute shell commands in a local environment. - - - `class BetaFunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool` - - 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) - - - `class BetaNamespaceTool` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool` - - 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). - - - `class BetaApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :additional_tools` - - The type of the item. Always `additional_tools`. - - - `:additional_tools` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCompactionItem` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `id: String` - - The unique ID of the compaction item. - - - `encrypted_content: String` - - The encrypted content that was produced by compaction. - - - `type: :compaction` - - The type of the item. Always `compaction`. - - - `:compaction` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ImageGenerationCall` - - 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 | :completed | :generating | :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: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall` - - 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[Logs{ logs, type} | Image{ type, url}]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class Logs` - - 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` - - - `class Image` - - 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 | :completed | :incomplete | 2 more` - - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - - `:in_progress` - - - `:completed` + - `name: String` - - `:incomplete` + The name of the function to call. - - `:interpreting` + - `parameters: Hash[Symbol, untyped]` - - `:failed` + A JSON schema object describing the parameters of the function. - - `type: :code_interpreter_call` + - `strict: bool` - 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: Agent{ agent_name}` + The type of the function tool. Always `function`. - The agent that produced this item. + - `:function` - - `agent_name: String` + - `allowed_callers: Array[:direct | :programmatic]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `class LocalShellCall` + - `:direct` - A tool call to run a command on the local shell. + - `:programmatic` - - `id: String` + - `defer_loading: bool` - The unique ID of the local shell call. + Whether this function is deferred and loaded via tool search. - - `action: Action{ command, env, type, 3 more}` + - `description: 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[String]` + - `output_schema: Hash[Symbol, untyped]` - The command to run. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `env: Hash[Symbol, String]` + - `class BetaFileSearchTool` - 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: Integer` + - `vector_store_ids: Array[String]` - Optional timeout in milliseconds for the command. + The IDs of the vector stores to search. - - `user: String` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - Optional user to run the command as. + A filter to apply. - - `working_directory: String` + - `class ComparisonFilter` - 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 | :completed | :incomplete` + - `type: :eq | :ne | :gt | 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: Agent{ 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 | Float | bool | Array[String | Float]` - - `class LocalShellCallOutput` + The value to compare against the attribute key; supports string, number, or boolean types. - The output of a local shell tool call. + - `String = String` - - `id: String` + - `Float = Float` - The unique ID of the local shell tool call generated by the model. + - `UnionMember2 = bool` - - `output: String` + - `UnionMember3 = Array[String | Float]` - A JSON string of the output of the local shell tool call. + - `String = String` - - `type: :local_shell_call_output` + - `Float = Float` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class CompoundFilter` - - `:local_shell_call_output` + Combine multiple filters using `and` or `or`. - - `agent: Agent{ agent_name}` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - The agent that produced this item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `agent_name: String` + - `class ComparisonFilter` - 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: :in_progress | :completed | :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 | :ne | :gt | 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 - - `class BetaResponseFunctionShellToolCall` + - `: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: Action{ commands, max_output_length, timeout_ms}` + - `:lt` - The shell commands and limits that describe how to run the tool call. + - `:lte` - - `commands: Array[String]` + - `:in` - - `max_output_length: Integer` + - `:nin` - Optional maximum number of characters to return from each command. + - `value: String | Float | bool | Array[String | Float]` - - `timeout_ms: Integer` + The value to compare against the attribute key; supports string, number, or boolean types. - Optional timeout in milliseconds for the commands. + - `String = String` - - `call_id: String` + - `Float = Float` - The unique ID of the shell tool call generated by the model. + - `UnionMember2 = bool` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `UnionMember3 = Array[String | Float]` - Represents the use of a local environment to perform shell actions. + - `String = String` - - `class BetaResponseLocalEnvironment` + - `Float = Float` - Represents the use of a local environment to perform shell actions. + - `UnionMember1 = untyped` - - `type: :local` + - `type: :and | :or` - The environment type. Always `local`. + Type of operation: `and` or `or`. - - `:local` + - `:and` - - `class BetaResponseContainerReference` + - `:or` - Represents a container created with /v1/containers. + - `max_num_results: Integer` - - `container_id: String` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: :container_reference` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The environment type. Always `container_reference`. + Ranking options for search. - - `:container_reference` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `status: :in_progress | :completed | :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: Float` - - `:in_progress` + The weight of the embedding in the reciprocal ranking fusion. - - `:completed` + - `text_weight: Float` - - `:incomplete` + The weight of the text in the reciprocal ranking fusion. - - `type: :shell_call` + - `ranker: :auto | :"default-2024-11-15"` - The type of the item. Always `shell_call`. + The ranker to use for the file search. - - `:shell_call` + - `:auto` - - `agent: Agent{ agent_name}` + - `:"default-2024-11-15"` - The agent that produced this item. + - `score_threshold: Float` - - `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. + - `class BetaComputerTool` - - `caller_: Direct{ type} | Program{ 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` - - `class Direct` + The type of the computer tool. Always `computer`. - - `type: :direct` + - `:computer` - - `:direct` + - `class BetaComputerUsePreviewTool` - - `class Program` + 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: Integer` - The call ID of the program item that produced this tool call. + The height of the computer display. - - `type: :program` + - `display_width: Integer` - - `:program` + The width of the computer display. - - `created_by: String` + - `environment: :windows | :mac | :linux | 2 more` - The ID of the entity that created this tool call. + The type of computer environment to control. - - `class BetaResponseFunctionShellToolCallOutput` + - `: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: Integer` + 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[Output{ outcome, stderr, stdout, created_by}]` + - `class BetaWebSearchTool` - An array of shell call output contents + 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). - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `type: :web_search | :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`. - - `class Timeout` + - `:web_search` - Indicates that the shell call exceeded its configured time limit. + - `:web_search_2025_08_26` - - `type: :timeout` + - `filters: Filters{ allowed_domains}` - The outcome type. Always `timeout`. + Filters for the search. - - `:timeout` + - `allowed_domains: Array[String]` - - `class Exit` + 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: Integer` + - `search_context_size: :low | :medium | :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: UserLocation{ city, country, region, 2 more}` - The standard error output that was captured. + The approximate location of the user. - - `stdout: String` + - `city: String` - The standard output that was captured. + Free text input for the city of the user, e.g. `San Francisco`. - - `created_by: String` + - `country: 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 | :completed | :incomplete` + - `region: 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: String` - - `:completed` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:incomplete` + - `type: :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` + - `class Mcp` - - `agent: Agent{ 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` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The type of the MCP tool. Always `mcp`. - The execution context that produced this tool call. + - `:mcp` - - `class Direct` + - `allowed_callers: Array[:direct | :programmatic]` - - `type: :direct` + The tool invocation context(s). - `:direct` - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - - `:program` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseApplyPatchToolCall` - - 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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class CreateFile` - - 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` - - - `class DeleteFile` - - 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` - - - `class UpdateFile` - - 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 | :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: Agent{ agent_name}` - - The agent that produced this item. + - `:programmatic` - - `agent_name: String` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - The canonical name of the agent that produced this item. + List of allowed tool names or a filter object. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `McpAllowedTools = Array[String]` - The execution context that produced this tool call. + A string array of allowed tool names - - `class Direct` + - `class McpToolFilter` - - `type: :direct` + A filter object to specify which tools are allowed. - - `:direct` + - `read_only: bool` - - `class 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. - - `caller_id: String` + - `tool_names: Array[String]` - The call ID of the program item that produced this tool call. + List of allowed tool names. - - `type: :program` + - `authorization: String` - - `:program` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `created_by: String` + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - The ID of the entity that created 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `class BetaResponseApplyPatchToolCallOutput` + Currently supported `connector_id` values are: - The output emitted by an apply patch 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` - - `id: String` + - `:connector_dropbox` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:connector_gmail` - - `call_id: String` + - `:connector_googlecalendar` - The unique ID of the apply patch tool call generated by the model. + - `:connector_googledrive` - - `status: :completed | :failed` + - `:connector_microsoftteams` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `:connector_outlookcalendar` - - `:completed` + - `:connector_outlookemail` - - `:failed` + - `:connector_sharepoint` - - `type: :apply_patch_call_output` + - `defer_loading: bool` - The type of the item. Always `apply_patch_call_output`. + Whether this MCP tool is deferred and discovered via tool search. - - `:apply_patch_call_output` + - `headers: Hash[Symbol, String]` - - `agent: Agent{ agent_name}` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The agent that produced this item. + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `agent_name: String` + Specify which of the MCP server's tools require approval. - The canonical name of the agent that produced this item. + - `class McpToolApprovalFilter` - - `caller_: Direct{ type} | Program{ 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. - The execution context that produced this tool call. + - `always: Always{ read_only, tool_names}` - - `class Direct` + A filter object to specify which tools are allowed. - - `type: :direct` + - `read_only: bool` - - `: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. - - `class Program` + - `tool_names: Array[String]` - - `caller_id: String` + List of allowed tool names. - The call ID of the program item that produced this tool call. + - `never: Never{ read_only, tool_names}` - - `type: :program` + A filter object to specify which tools are allowed. - - `:program` + - `read_only: bool` - - `created_by: String` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The ID of the entity that created this tool call output. + - `tool_names: Array[String]` - - `output: String` + List of allowed tool names. - Optional textual output returned by the apply patch tool. + - `McpToolApprovalSetting = :always | :never` - - `class McpCall` + 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 invocation of a tool on an MCP server. + - `:always` - - `id: String` + - `:never` - The unique ID of the tool call. + - `server_description: String` - - `arguments: String` + Optional description of the MCP server, used to provide more context. - A JSON string of the arguments passed to the tool. + - `server_url: String` - - `name: String` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The name of the tool that was run. + - `tunnel_id: String` - - `server_label: String` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The label of the MCP server running the tool. + - `class CodeInterpreter` - - `type: :mcp_call` + A tool that runs Python code to help generate a response to a prompt. - The type of the item. Always `mcp_call`. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `:mcp_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. - - `agent: Agent{ agent_name}` + - `String = String` - The agent that produced this item. + The container ID. - - `agent_name: String` + - `class CodeInterpreterToolAuto` - The canonical name of the agent that produced this item. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `approval_request_id: String` + - `type: :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. + Always `auto`. - - `error: String` + - `:auto` - The error from the tool call, if any. + - `file_ids: Array[String]` - - `output: String` + An optional list of uploaded files to make available to your code. - The output from the tool call. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `status: :in_progress | :completed | :incomplete | 2 more` + The memory limit for the code interpreter 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: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `:failed` + Network access policy for the container. - - `class McpListTools` + - `class BetaContainerNetworkPolicyDisabled` - A list of tools available on an MCP server. + - `type: :disabled` - - `id: String` + Disable outbound network access. Always `disabled`. - The unique ID of the list. + - `:disabled` - - `server_label: String` + - `class BetaContainerNetworkPolicyAllowlist` - The label of the MCP server. + - `allowed_domains: Array[String]` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + A list of allowed domains when type is `allowlist`. - The tools available on the server. + - `type: :allowlist` - - `input_schema: untyped` + Allow outbound network access only to specified domains. Always `allowlist`. - The JSON schema describing the tool's input. + - `:allowlist` - - `name: String` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - The name of the tool. + Optional domain-scoped secrets for allowlisted domains. - - `annotations: untyped` + - `domain: String` - Additional annotations about the tool. + The domain associated with the secret. - - `description: String` + - `name: String` - The description of the tool. + The name of the secret to inject for the domain. - - `type: :mcp_list_tools` + - `value: String` - The type of the item. Always `mcp_list_tools`. + The secret value to inject for the domain. - - `:mcp_list_tools` + - `type: :code_interpreter` - - `agent: Agent{ agent_name}` + The type of the code interpreter tool. Always `code_interpreter`. - The agent that produced this item. + - `:code_interpreter` - - `agent_name: String` + - `allowed_callers: Array[:direct | :programmatic]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `error: String` + - `:direct` - Error message if the server could not list tools. + - `:programmatic` - - `class McpApprovalRequest` + - `class ProgrammaticToolCalling` - A request for human approval of a tool invocation. + - `type: :programmatic_tool_calling` - - `id: String` + The type of the tool. Always `programmatic_tool_calling`. - The unique ID of the approval request. + - `:programmatic_tool_calling` - - `arguments: String` + - `class ImageGeneration` - A JSON string of arguments for the tool. + A tool that generates images using the GPT image models. - - `name: String` + - `type: :image_generation` - The name of the tool to run. + The type of the image generation tool. Always `image_generation`. - - `server_label: String` + - `:image_generation` - The label of the MCP server making the request. + - `action: :generate | :edit | :auto` - - `type: :mcp_approval_request` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the item. Always `mcp_approval_request`. + - `:generate` - - `:mcp_approval_request` + - `:edit` - - `agent: Agent{ agent_name}` + - `:auto` - The agent that produced this item. + - `background: :transparent | :opaque | :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. - - `class McpApprovalResponse` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A response to an MCP approval request. + - `:transparent` - - `id: String` + - `:opaque` - The unique ID of the approval response + - `:auto` - - `approval_request_id: String` + - `input_fidelity: :high | :low` - The ID of the approval request being answered. + 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`. - - `approve: bool` + - `:high` - Whether the request was approved. + - `:low` - - `type: :mcp_approval_response` + - `input_image_mask: InputImageMask{ file_id, image_url}` - The type of the item. Always `mcp_approval_response`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `:mcp_approval_response` + - `file_id: String` - - `agent: Agent{ agent_name}` + File ID for the mask image. - The agent that produced this item. + - `image_url: String` - - `agent_name: String` + Base64-encoded mask image. - The canonical name of the agent that produced this item. + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `reason: String` + The image generation model to use. Default: `gpt-image-1`. - Optional reason for the decision. + - `String = String` - - `class BetaResponseCustomToolCall` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - A call to a custom tool created by the model. + The image generation model to use. Default: `gpt-image-1`. - - `call_id: String` + - `:"gpt-image-1"` - An identifier used to map this custom tool call to a tool call output. + - `:"gpt-image-1-mini"` - - `input: String` + - `:"gpt-image-2"` - The input for the custom tool call generated by the model. + - `:"gpt-image-2-2026-04-21"` - - `name: String` + - `:"gpt-image-1.5"` - The name of the custom tool being called. + - `:"chatgpt-image-latest"` - - `type: :custom_tool_call` + - `moderation: :auto | :low` - The type of the custom tool call. Always `custom_tool_call`. + Moderation level for the generated image. Default: `auto`. - - `:custom_tool_call` + - `:auto` - - `id: String` + - `:low` - The unique ID of the custom tool call in the OpenAI platform. + - `output_compression: Integer` - - `agent: Agent{ agent_name}` + Compression level for the output image. Default: 100. - The agent that produced this item. + - `output_format: :png | :webp | :jpeg` - - `agent_name: String` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The canonical name of the agent that produced this item. + - `:png` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:webp` - The execution context that produced this tool call. + - `:jpeg` - - `class Direct` + - `partial_images: Integer` - - `type: :direct` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `:direct` + - `quality: :low | :medium | :high | :auto` - - `class Program` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller_id: String` + - `:low` - The call ID of the program item that produced this tool call. + - `:medium` - - `type: :program` + - `:high` - - `:program` + - `:auto` - - `namespace: String` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - The namespace of the custom tool being called. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class BetaResponseCustomToolCallOutputItem` + - `String = String` - The output of a custom tool call from your code, being sent back to the model. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 custom tool call output item. + - `:"1024x1024"` - - `status: :in_progress | :completed | :incomplete` + - `:"1024x1536"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:"1536x1024"` - - `:in_progress` + - `:auto` - - `:completed` + - `class LocalShell` - - `:incomplete` + A tool that allows the model to execute shell commands in a local environment. - - `created_by: String` + - `type: :local_shell` - The identifier of the actor that created the item. + The type of the local shell tool. Always `local_shell`. - - `output_index: Integer` + - `:local_shell` - The index of the output item that was marked done. + - `class BetaFunctionShellTool` - - `sequence_number: Integer` + A tool that allows the model to execute shell commands. - The sequence number of this event. + - `type: :shell` - - `type: :"response.output_item.done"` + The type of the shell tool. Always `shell`. - The type of the event. Always `response.output_item.done`. + - `:shell` - - `:"response.output_item.done"` + - `allowed_callers: Array[:direct | :programmatic]` - - `agent: Agent{ 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. + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` -### Beta Response Output Message + - `class BetaContainerAuto` -- `class BetaResponseOutputMessage` + - `type: :container_auto` - An output message from the model. + Automatically creates a container for this request - - `id: String` + - `:container_auto` - The unique ID of the output message. + - `file_ids: Array[String]` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + An optional list of uploaded files to make available to your code. - The content of the output message. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `class BetaResponseOutputText` + The memory limit for the container. - A text output from the model. + - `:"1g"` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `:"4g"` - The annotations of the text output. + - `:"16g"` - - `class FileCitation` + - `:"64g"` - A citation to a file. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `file_id: String` + Network access policy for the container. - The ID of the file. + - `class BetaContainerNetworkPolicyDisabled` - - `filename: String` + - `class BetaContainerNetworkPolicyAllowlist` - The filename of the file cited. + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - - `index: Integer` + An optional list of skills referenced by id or inline data. - The index of the file in the list of files. + - `class BetaSkillReference` - - `type: :file_citation` + - `skill_id: String` - The type of the file citation. Always `file_citation`. + The ID of the referenced skill. - - `:file_citation` + - `type: :skill_reference` - - `class URLCitation` + References a skill created with the /v1/skills endpoint. - A citation for a web resource used to generate a model response. + - `:skill_reference` - - `end_index: Integer` + - `version: String` - The index of the last character of the URL citation in the message. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `start_index: Integer` + - `class BetaInlineSkill` - The index of the first character of the URL citation in the message. + - `description: String` - - `title: String` + The description of the skill. - The title of the web resource. + - `name: String` - - `type: :url_citation` + The name of the skill. - The type of the URL citation. Always `url_citation`. + - `source: BetaInlineSkillSource` - - `:url_citation` + Inline skill payload - - `url: String` + - `data: String` - The URL of the web resource. + Base64-encoded skill zip bundle. - - `class ContainerFileCitation` + - `media_type: :"application/zip"` - A citation for a container file used to generate a model response. + The media type of the inline skill payload. Must be `application/zip`. - - `container_id: String` + - `:"application/zip"` - The ID of the container file. + - `type: :base64` - - `end_index: Integer` + The type of the inline skill source. Must be `base64`. - The index of the last character of the container file citation in the message. + - `:base64` - - `file_id: String` + - `type: :inline` - The ID of the file. + Defines an inline skill for this request. - - `filename: String` + - `:inline` - The filename of the container file cited. + - `class BetaLocalEnvironment` - - `start_index: Integer` + - `type: :local` - The index of the first character of the container file citation in the message. + Use a local computer environment. - - `type: :container_file_citation` + - `:local` - The type of the container file citation. Always `container_file_citation`. + - `skills: Array[BetaLocalSkill]` - - `:container_file_citation` + An optional list of skills. - - `class FilePath` + - `description: String` - A path to a file. + The description of the skill. - - `file_id: String` + - `name: String` - The ID of the file. + The name of the skill. - - `index: Integer` + - `path: String` - The index of the file in the list of files. + The path to the directory containing the skill. - - `type: :file_path` + - `class BetaContainerReference` - The type of the file path. Always `file_path`. + - `container_id: String` - - `:file_path` + The ID of the referenced container. - - `text: String` + - `type: :container_reference` - The text output from the model. + References a container created with the /v1/containers endpoint - - `type: :output_text` + - `:container_reference` - The type of the output text. Always `output_text`. + - `class BetaCustomTool` - - `: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) - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `name: String` - - `token: String` + The name of the custom tool, used to identify it in tool calls. - - `bytes: Array[Integer]` + - `type: :custom` - - `logprob: Float` + The type of the custom tool. Always `custom`. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `:custom` - - `token: String` + - `allowed_callers: Array[:direct | :programmatic]` - - `bytes: Array[Integer]` + The tool invocation context(s). - - `logprob: Float` + - `:direct` - - `class BetaResponseOutputRefusal` + - `:programmatic` - A refusal from the model. + - `defer_loading: bool` - - `refusal: String` + Whether this tool should be deferred and discovered via tool search. - The refusal explanation from the model. + - `description: String` - - `type: :refusal` + Optional description of the custom tool, used to provide more context. - The type of the refusal. Always `refusal`. + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `:refusal` + The input format for the custom tool. Default is unconstrained text. - - `role: :assistant` + - `class Text` - The role of the output message. Always `assistant`. + Unconstrained free-form text. - - `:assistant` + - `type: :text` - - `status: :in_progress | :completed | :incomplete` + Unconstrained text format. Always `text`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `:text` - - `:in_progress` + - `class Grammar` - - `:completed` + A grammar defined by the user. - - `:incomplete` + - `definition: String` - - `type: :message` + The grammar definition. - The type of the output message. Always `message`. + - `syntax: :lark | :regex` - - `:message` + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent: Agent{ agent_name}` + - `:lark` - The agent that produced this item. + - `:regex` - - `agent_name: String` + - `type: :grammar` - The canonical name of the agent that produced this item. + Grammar format. Always `grammar`. - - `phase: :commentary` + - `:grammar` - 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. + - `class BetaNamespaceTool` - - `:commentary` + Groups function/custom tools under a shared namespace. -### Beta Response Output Refusal + - `description: String` -- `class BetaResponseOutputRefusal` + A description of the namespace shown to the model. - A refusal from the model. + - `name: String` - - `refusal: String` + The namespace name used in tool calls (for example, `crm`). - The refusal explanation from the model. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `type: :refusal` + The function/custom tools available inside this namespace. - The type of the refusal. Always `refusal`. + - `class Function` - - `:refusal` + - `name: String` -### Beta Response Output Text + - `type: :function` -- `class BetaResponseOutputText` + - `:function` - A text output from the model. + - `allowed_callers: Array[:direct | :programmatic]` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The tool invocation context(s). - The annotations of the text output. + - `:direct` - - `class FileCitation` + - `:programmatic` - A citation to a file. + - `defer_loading: bool` - - `file_id: String` + Whether this function should be deferred and discovered via tool search. - The ID of the file. + - `description: String` - - `filename: String` + - `output_schema: Hash[Symbol, untyped]` - The filename of the file cited. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `index: Integer` + - `parameters: untyped` - The index of the file in the list of files. + - `strict: bool` - - `type: :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 type of the file citation. Always `file_citation`. + - `class BetaCustomTool` - - `: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) - - `class URLCitation` + - `type: :namespace` - A citation for a web resource used to generate a model response. + The type of the tool. Always `namespace`. - - `end_index: Integer` + - `:namespace` - The index of the last character of the URL citation in the message. + - `class BetaToolSearchTool` - - `start_index: Integer` + Hosted or BYOT tool search configuration for deferred tools. - The index of the first character of the URL citation in the message. + - `type: :tool_search` - - `title: String` + The type of the tool. Always `tool_search`. - The title of the web resource. + - `:tool_search` - - `type: :url_citation` + - `description: String` - The type of the URL citation. Always `url_citation`. + Description shown to the model for a client-executed tool search tool. - - `:url_citation` + - `execution: :server | :client` - - `url: String` + Whether tool search is executed by the server or by the client. - The URL of the web resource. + - `:server` - - `class ContainerFileCitation` + - `:client` - A citation for a container file used to generate a model response. + - `parameters: untyped` - - `container_id: String` + Parameter schema for a client-executed tool search tool. - The ID of the container file. + - `class BetaWebSearchPreviewTool` - - `end_index: Integer` + 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 last character of the container file citation in the message. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `file_id: String` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The ID of the file. + - `:web_search_preview` - - `filename: String` + - `:web_search_preview_2025_03_11` - The filename of the container file cited. + - `search_content_types: Array[:text | :image]` - - `start_index: Integer` + - `:text` - The index of the first character of the container file citation in the message. + - `:image` - - `type: :container_file_citation` + - `search_context_size: :low | :medium | :high` - The type of the container file citation. Always `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. - - `:container_file_citation` + - `:low` - - `class FilePath` + - `:medium` - A path to a file. + - `:high` - - `file_id: String` + - `user_location: UserLocation{ type, city, country, 2 more}` - The ID of the file. + The user's location. - - `index: Integer` + - `type: :approximate` - The index of the file in the list of files. + The type of location approximation. Always `approximate`. - - `type: :file_path` + - `:approximate` - The type of the file path. Always `file_path`. + - `city: String` - - `:file_path` + Free text input for the city of the user, e.g. `San Francisco`. - - `text: String` + - `country: String` - The text output from the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: :output_text` + - `region: String` - The type of the output text. Always `output_text`. + Free text input for the region of the user, e.g. `California`. - - `:output_text` + - `timezone: String` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `token: String` + - `class BetaApplyPatchTool` - - `bytes: Array[Integer]` + Allows the assistant to create, delete, or update files using unified diffs. - - `logprob: Float` + - `type: :apply_patch` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + The type of the tool. Always `apply_patch`. - - `token: String` + - `:apply_patch` - - `bytes: Array[Integer]` + - `allowed_callers: Array[:direct | :programmatic]` - - `logprob: Float` + The tool invocation context(s). -### Beta Response Output Text Annotation Added Event + - `:direct` -- `class BetaResponseOutputTextAnnotationAddedEvent` + - `:programmatic` - Emitted when an annotation is added to output text content. + - `type: :tool_search_output` - - `annotation: untyped` + The item type. Always `tool_search_output`. - The annotation object being added. (See annotation schema for details.) + - `:tool_search_output` - - `annotation_index: Integer` + - `id: String` - The index of the annotation within the content part. + The unique ID of this tool search output. - - `content_index: Integer` + - `agent: Agent{ agent_name}` - The index of the content part within the output item. + The agent that produced this item. - - `item_id: String` + - `agent_name: String` - The unique identifier of the item to which the annotation is being added. + The canonical name of the agent that produced this item. - - `output_index: Integer` + - `call_id: String` - The index of the output item in the response's output array. + The unique ID of the tool search call generated by the model. - - `sequence_number: Integer` + - `execution: :server | :client` - The sequence number of this event. + Whether tool search was executed by the server or by the client. - - `type: :"response.output_text.annotation.added"` + - `:server` - The type of the event. Always 'response.output_text.annotation.added'. + - `:client` - - `:"response.output_text.annotation.added"` + - `status: :in_progress | :completed | :incomplete` - - `agent: Agent{ agent_name}` + The status of the tool search output. - 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 Prompt +### Beta Response Usage -- `class BetaResponsePrompt` +- `class BetaResponseUsage` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `id: String` + - `input_tokens: Integer` - The unique identifier of the prompt template to use. + The number of input tokens. - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - 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 detailed breakdown of the input tokens. - - `String = String` + - `cache_write_tokens: Integer` - - `class BetaResponseInputText` + The number of input tokens that were written to the cache. - A text input to the model. + - `cached_tokens: Integer` - - `text: String` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The text input to the model. + - `output_tokens: Integer` - - `type: :input_text` + The number of output tokens. - The type of the input item. Always `input_text`. + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - - `:input_text` + A detailed breakdown of the output tokens. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `reasoning_tokens: Integer` - Marks the exact end of a reusable 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 reasoning tokens. - - `mode: :explicit` + - `total_tokens: Integer` - The breakpoint mode. Always `explicit`. + The total number of tokens used. - - `:explicit` +### Beta Response Web Search Call Completed Event - - `class BetaResponseInputImage` +- `class BetaResponseWebSearchCallCompletedEvent` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Emitted when a web search call is completed. - - `detail: :low | :high | :auto | :original` + - `item_id: String` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Unique ID for the output item associated with the web search call. - - `:low` + - `output_index: Integer` - - `:high` + The index of the output item that the web search call is associated with. - - `:auto` + - `sequence_number: Integer` - - `:original` + The sequence number of the web search call being processed. - - `type: :input_image` + - `type: :"response.web_search_call.completed"` - The type of the input item. Always `input_image`. + The type of the event. Always `response.web_search_call.completed`. - - `:input_image` + - `:"response.web_search_call.completed"` - - `file_id: String` + - `agent: Agent{ agent_name}` - The ID of the file to be sent to the model. + The agent that owns this multi-agent streaming event. - - `image_url: 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: PromptCacheBreakpoint{ mode}` +### Beta Response Web Search Call In Progress 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. +- `class BetaResponseWebSearchCallInProgressEvent` - - `mode: :explicit` + Emitted when a web search call is initiated. - The breakpoint mode. Always `explicit`. + - `item_id: String` - - `:explicit` + Unique ID for the output item associated with the web search call. - - `class BetaResponseInputFile` + - `output_index: Integer` - A file input to the model. + The index of the output item that the web search call is associated with. - - `type: :input_file` + - `sequence_number: Integer` - The type of the input item. Always `input_file`. + The sequence number of the web search call being processed. - - `:input_file` + - `type: :"response.web_search_call.in_progress"` - - `detail: :auto | :low | :high` + The type of the event. Always `response.web_search_call.in_progress`. - 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`. + - `:"response.web_search_call.in_progress"` - - `:auto` + - `agent: Agent{ agent_name}` - - `:low` + The agent that owns this multi-agent streaming event. - - `:high` + - `agent_name: String` - - `file_data: String` + The canonical name of the agent that produced this item. - The content of the file to be sent to the model. +### Beta Response Web Search Call Searching Event - - `file_id: String` +- `class BetaResponseWebSearchCallSearchingEvent` - The ID of the file to be sent to the model. + Emitted when a web search call is executing. - - `file_url: String` + - `item_id: String` - The URL of the file to be sent to the model. + Unique ID for the output item associated with the web search call. - - `filename: String` + - `output_index: Integer` - The name of the file to be sent to the model. + The index of the output item that the web search call is associated with. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `sequence_number: Integer` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The sequence number of the web search call being processed. - - `mode: :explicit` + - `type: :"response.web_search_call.searching"` - The breakpoint mode. Always `explicit`. + The type of the event. Always `response.web_search_call.searching`. - - `:explicit` + - `:"response.web_search_call.searching"` - - `version: String` + - `agent: Agent{ agent_name}` - Optional version of the prompt template. + The agent that owns this multi-agent streaming event. -### Beta Response Queued Event + - `agent_name: String` -- `class BetaResponseQueuedEvent` + The canonical name of the agent that produced this item. - Emitted when a response is queued and waiting to be processed. +### Beta Responses Client Event - - `response: BetaResponse` +- `BetaResponsesClientEvent = ResponseCreate{ type, background, context_management, 30 more} | BetaResponseInjectEvent` - The full response object that is queued. + Client events accepted by the Responses WebSocket server. - - `id: String` + - `class ResponseCreate` - Unique identifier for this Response. + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`. - - `created_at: Float` + Notes: - Unix timestamp (in seconds) of when this Response was created. + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. - - `error: BetaResponseError` + - `type: :"response.create"` - An error object returned when the model fails to generate a Response. + The type of the client event. Always `response.create`. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `:"response.create"` - The error code for the response. + - `background: bool` - - `:server_error` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `:rate_limit_exceeded` + - `context_management: Array[ContextManagement{ type, compact_threshold}]` - - `:invalid_prompt` + Context management configuration for this request. - - `:bio_policy` + - `type: String` - - `:vector_store_timeout` + The context management entry type. Currently only 'compaction' is supported. - - `:invalid_image` + - `compact_threshold: Integer` - - `:invalid_image_format` + Token threshold at which compaction should be triggered for this entry. - - `:invalid_base64_image` + - `conversation: String | BetaResponseConversationParam` - - `:invalid_image_url` + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - - `:image_too_large` + - `String = String` - - `:image_too_small` + The unique ID of the conversation. - - `:image_parse_error` + - `class BetaResponseConversationParam` - - `:image_content_policy_violation` + The conversation that this response belongs to. - - `:invalid_image_mode` + - `id: String` - - `:image_file_too_large` + The unique ID of the conversation. - - `:unsupported_image_media_type` + - `include: Array[BetaResponseIncludable]` - - `:empty_image_file` + Specify additional output data to include in the model response. Currently supported values are: - - `:failed_to_download_image` + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `:image_file_not_found` + - `:"file_search_call.results"` - - `message: String` + - `:"web_search_call.results"` - A human-readable description of the error. + - `:"web_search_call.action.sources"` - - `incomplete_details: IncompleteDetails{ reason}` + - `:"message.input_image.image_url"` - Details about why the response is incomplete. + - `:"computer_call_output.output.image_url"` - - `reason: :max_output_tokens | :content_filter` + - `:"code_interpreter_call.outputs"` - The reason why the response is incomplete. + - `:"reasoning.encrypted_content"` - - `:max_output_tokens` + - `:"message.output_text.logprobs"` - - `:content_filter` + - `input: String | BetaResponseInput` - - `instructions: String | Array[BetaResponseInputItem]` + Text, image, or file inputs to the model, used to generate a response. - A system (or developer) message inserted into the model's context. + Learn 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. + - [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) - `String = String` A text input to the model, equivalent to a text input with the - `developer` role. + `user` role. - - `InputItemList = Array[BetaResponseInputItem]` + - `BetaResponseInput = Array[BetaResponseInputItem]` A list of one or many input items to the model, containing different content types. @@ -117383,7 +129329,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :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 @@ -117391,6 +129337,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -117630,7 +129578,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -117638,6 +129586,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -118810,7 +130760,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -118820,7 +130770,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -118867,7 +130821,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -118877,7 +130831,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -120563,1222 +132521,2068 @@ puts(beta_compacted_response) - `type: :apply_patch_call_output` - The type of the item. Always `apply_patch_call_output`. + The type of the item. Always `apply_patch_call_output`. + + - `:apply_patch_call_output` + + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `output: String` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools` + + 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[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class McpCall` + + 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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_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. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class BetaResponseCustomToolCallOutput` + + 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + 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: String` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + 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: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `instructions: String` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `max_output_tokens: Integer` + + 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: Integer` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. + + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 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"` + + - `:"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 = String` + + - `moderation: Moderation{ model, policy}` + + Configuration for running moderation on the input and output of this response. + + - `model: String` + + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + + - `policy: Policy{ input, output}` + + The policy to apply to moderated response input and output. + + - `input: Input{ mode}` + + The moderation policy for the response input. + + - `mode: :score | :block` + + - `:score` + + - `:block` + + - `output: Output{ mode}` + + The moderation policy for the response output. + + - `mode: :score | :block` + + - `:score` + + - `:block` - - `:apply_patch_call_output` + - `multi_agent: MultiAgent{ enabled, max_concurrent_subagents}` - - `id: String` + Configuration for server-hosted multi-agent execution. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `enabled: bool` - - `agent: Agent{ agent_name}` + Whether to enable server-hosted multi-agent execution for this response. - The agent that produced this item. + - `max_concurrent_subagents: Integer` - - `agent_name: String` + `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 canonical name of the agent that produced this item. + - `parallel_tool_calls: bool` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Whether to allow the model to run tool calls in parallel. - The execution context that produced this tool call. + - `previous_response_id: String` - - `class Direct` + 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: :direct` + - `prompt: BetaResponsePrompt` - The caller type. Always `direct`. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `:direct` + - `id: String` - - `class Program` + The unique identifier of the prompt template to use. - - `caller_id: String` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The call ID of the program item that produced this tool call. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `type: :program` + - `String = String` - The caller type. Always `program`. + - `class BetaResponseInputText` - - `:program` + A text input to the model. - - `output: String` + - `class BetaResponseInputImage` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class McpListTools` + - `class BetaResponseInputFile` - A list of tools available on an MCP server. + A file input to the model. - - `id: String` + - `version: String` - The unique ID of the list. + Optional version of the prompt template. - - `server_label: String` + - `prompt_cache_key: String` - The label of the MCP server. + 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). - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - The tools available on the server. + 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. - - `input_schema: untyped` + - `mode: :implicit | :explicit` - The JSON schema describing the tool's input. + 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. - - `name: String` + - `:implicit` - The name of the tool. + - `:explicit` - - `annotations: untyped` + - `ttl: :"30m"` - Additional annotations about the tool. + 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. - - `description: String` + - `:"30m"` - The description of the tool. + - `prompt_cache_retention: :in_memory | :"24h"` - - `type: :mcp_list_tools` + Deprecated. Use `prompt_cache_options.ttl` instead. - The type of the item. Always `mcp_list_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. - - `:mcp_list_tools` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `agent: Agent{ agent_name}` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The agent that produced this item. + - `:in_memory` - - `agent_name: String` + - `:"24h"` - The canonical name of the agent that produced this item. + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - - `error: String` + **gpt-5 and o-series models only** - Error message if the server could not list tools. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `class McpApprovalRequest` + - `context: :auto | :current_turn | :all_turns` - A request for human approval of a tool invocation. + 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. - - `id: String` + - `:auto` - The unique ID of the approval request. + - `:current_turn` - - `arguments: String` + - `:all_turns` - A JSON string of arguments for the tool. + - `effort: :none | :minimal | :low | 4 more` - - `name: 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 name of the tool to run. + - `:none` - - `server_label: String` + - `:minimal` - The label of the MCP server making the request. + - `:low` - - `type: :mcp_approval_request` + - `:medium` - The type of the item. Always `mcp_approval_request`. + - `:high` - - `:mcp_approval_request` + - `:xhigh` - - `agent: Agent{ agent_name}` + - `:max` - The agent that produced this item. + - `generate_summary: :auto | :concise | :detailed` - - `agent_name: String` + **Deprecated:** use `summary` instead. - The canonical name of the agent that produced this item. + 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`. - - `class McpApprovalResponse` + - `:auto` - A response to an MCP approval request. + - `:concise` - - `approval_request_id: String` + - `:detailed` - The ID of the approval request being answered. + - `mode: String | :standard | :pro` - - `approve: bool` + Controls the reasoning execution mode for the request. - Whether the request was approved. + When returned on a response, this is the effective execution mode. - - `type: :mcp_approval_response` + - `String = String` - The type of the item. Always `mcp_approval_response`. + - `Mode = :standard | :pro` - - `:mcp_approval_response` + 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 approval response + - `:standard` - - `agent: Agent{ agent_name}` + - `:pro` - The agent that produced this item. + - `summary: :auto | :concise | :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`. - - `reason: String` + - `:auto` - Optional reason for the decision. + - `:concise` - - `class McpCall` + - `:detailed` - An invocation of a tool on an MCP server. + - `safety_identifier: String` - - `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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The unique ID of the tool call. + - `service_tier: :auto | :default | :flex | 2 more` - - `arguments: String` + Specifies the processing type used for serving the request. - A JSON string of the arguments passed to the tool. + - 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'. - - `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 name of the tool that was run. + - `:auto` - - `server_label: String` + - `:default` - The label of the MCP server running the tool. + - `:flex` - - `type: :mcp_call` + - `:scale` - The type of the item. Always `mcp_call`. + - `:priority` - - `:mcp_call` + - `store: bool` - - `agent: Agent{ agent_name}` + Whether to store the generated model response for later retrieval via + API. - The agent that produced this item. + - `stream: bool` - - `agent_name: 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](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. - The canonical name of the agent that produced this item. + - `stream_options: StreamOptions{ include_obfuscation}` - - `approval_request_id: String` + Options for streaming responses. Only set this when you set `stream: true`. - 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. + - `include_obfuscation: bool` - - `error: String` + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. - The error from the tool call, if any. + - `temperature: Float` - - `output: 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 output from the tool call. + - `text: BetaResponseTextConfig` - - `status: :in_progress | :completed | :incomplete | 2 more` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `:in_progress` + - `format_: BetaResponseFormatTextConfig` - - `:completed` + An object specifying the format that the model must output. - - `:incomplete` + 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). - - `:calling` + The default format is `{ "type": "text" }` with no additional options. - - `:failed` + **Not recommended for gpt-4o and newer models:** - - `class BetaResponseCustomToolCallOutput` + 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 output of a custom tool call from your code, being sent back to the model. + - `class Text` - - `call_id: String` + Default response format. Used to generate text responses. - The call ID, used to map this custom tool call output to a custom tool call. + - `type: :text` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The type of response format being defined. Always `text`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `:text` - - `String = String` + - `class BetaResponseFormatTextJSONSchemaConfig` - A string of the output of the 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). - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `name: String` - Text, image, or file output of the 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. - - `class BetaResponseInputText` + - `schema: Hash[Symbol, untyped]` - A text input to the model. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `class BetaResponseInputImage` + - `type: :json_schema` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The type of response format being defined. Always `json_schema`. - - `class BetaResponseInputFile` + - `:json_schema` - A file input to the model. + - `description: String` - - `type: :custom_tool_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 custom tool call output. Always `custom_tool_call_output`. + - `strict: bool` - - `:custom_tool_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). - - `id: String` + - `class JSONObject` - The unique ID of the custom tool call output in the OpenAI platform. + 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: Agent{ agent_name}` + - `type: :json_object` - The agent that produced this item. + The type of response format being defined. Always `json_object`. - - `agent_name: String` + - `:json_object` - The canonical name of the agent that produced this item. + - `verbosity: :low | :medium | :high` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The execution context that produced this tool call. + - `:low` - - `class Direct` + - `:medium` - - `type: :direct` + - `:high` - The caller type. Always `direct`. + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `:direct` + 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. - - `class Program` + - `BetaToolChoiceOptions = :none | :auto | :required` - - `caller_id: String` + Controls which (if any) tool is called by the model. - The call ID of the program item that produced this tool call. + `none` means the model will not call any tool and instead generates a message. - - `type: :program` + `auto` means the model can pick between generating a message or calling one or + more tools. - The caller type. Always `program`. + `required` means the model must call one or more tools. - - `:program` + - `:none` - - `class BetaResponseCustomToolCall` + - `:auto` - A call to a custom tool created by the model. + - `:required` - - `call_id: String` + - `class BetaToolChoiceAllowed` - An identifier used to map this custom tool call to a tool call output. + Constrains the tools available to the model to a pre-defined set. - - `input: String` + - `mode: :auto | :required` - The input for the custom tool call generated by the model. + Constrains the tools available to the model to a pre-defined set. - - `name: String` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The name of the custom tool being called. + `required` requires the model to call one or more of the allowed tools. - - `type: :custom_tool_call` + - `:auto` - The type of the custom tool call. Always `custom_tool_call`. + - `:required` - - `:custom_tool_call` + - `tools: Array[Hash[Symbol, untyped]]` - - `id: String` + A list of tool definitions that the model should be allowed to call. - The unique ID of the custom tool call in the OpenAI platform. + For the Responses API, the list of tool definitions might look like: - - `agent: Agent{ agent_name}` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The agent that produced this item. + - `type: :allowed_tools` - - `agent_name: String` + Allowed tool configuration type. Always `allowed_tools`. - The canonical name of the agent that produced this item. + - `:allowed_tools` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class BetaToolChoiceTypes` - The execution context that produced this tool call. + 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). - - `class Direct` + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `type: :direct` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `:direct` + Allowed values are: - - `class Program` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `caller_id: String` + - `:file_search` - The call ID of the program item that produced this tool call. + - `:web_search_preview` - - `type: :program` + - `:computer` - - `:program` + - `:computer_use_preview` - - `namespace: String` + - `:computer_use` - The namespace of the custom tool being called. + - `:web_search_preview_2025_03_11` - - `class CompactionTrigger` + - `:image_generation` - Compacts the current context. Must be the final input item. + - `:code_interpreter` - - `type: :compaction_trigger` + - `class BetaToolChoiceFunction` - The type of the item. Always `compaction_trigger`. + Use this option to force the model to call a specific function. - - `:compaction_trigger` + - `name: String` - - `agent: Agent{ agent_name}` + The name of the function to call. - The agent that produced this item. + - `type: :function` - - `agent_name: String` + For function calling, the type is always `function`. - The canonical name of the agent that produced this item. + - `:function` - - `class ItemReference` + - `class BetaToolChoiceMcp` - An internal identifier for an item to reference. + Use this option to force the model to call a specific tool on a remote MCP server. - - `id: String` + - `server_label: String` - The ID of the item to reference. + The label of the MCP server to use. - - `agent: Agent{ 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: String` - - `type: :item_reference` + The name of the tool to call on the server. - The type of item to reference. Always `item_reference`. + - `class BetaToolChoiceCustom` - - `:item_reference` + Use this option to force the model to call a specific custom tool. - - `class Program` + - `name: String` - - `id: String` + The name of the custom tool to call. - The unique ID of this program item. + - `type: :custom` - - `call_id: String` + For custom tool calling, the type is always `custom`. - The stable call ID of the program item. + - `:custom` - - `code: String` + - `class BetaSpecificProgrammaticToolCallingParam` - The JavaScript source executed by programmatic tool calling. + - `type: :programmatic_tool_calling` - - `fingerprint: String` + The tool to call. Always `programmatic_tool_calling`. - Opaque program replay fingerprint that must be round-tripped. + - `:programmatic_tool_calling` - - `type: :program` + - `class BetaToolChoiceApplyPatch` - The item type. Always `program`. + Forces the model to call the apply_patch tool when executing a tool call. - - `:program` + - `type: :apply_patch` - - `agent: Agent{ agent_name}` + The tool to call. Always `apply_patch`. - The agent that produced this item. + - `:apply_patch` - - `agent_name: String` + - `class BetaToolChoiceShell` - The canonical name of the agent that produced this item. + Forces the model to call the shell tool when a tool call is required. - - `class ProgramOutput` + - `type: :shell` - - `id: String` + The tool to call. Always `shell`. - The unique ID of this program output item. + - `:shell` - - `call_id: String` + - `tools: Array[BetaTool]` - The call ID of the program 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. - - `result: String` + We support the following categories of tools: - The result produced by the program item. + - **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. - - `status: :completed | :incomplete` + - `class BetaFunctionTool` - The terminal status of the program 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). - - `:completed` + - `class BetaFileSearchTool` - - `: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: :program_output` + - `class BetaComputerTool` - The item type. Always `program_output`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:program_output` + - `class BetaComputerUsePreviewTool` - - `agent: Agent{ 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. + - `class BetaWebSearchTool` - - `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. + - `class Mcp` - - `metadata: Hash[Symbol, 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). - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `class CodeInterpreter` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A tool that runs Python code to help generate a response to a prompt. - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `class ProgrammaticToolCalling` - 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. + - `class ImageGeneration` - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + A tool that generates images using the GPT image models. - 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. + - `class LocalShell` - - `:"gpt-5.6-sol"` + A tool that allows the model to execute shell commands in a local environment. - - `:"gpt-5.6-terra"` + - `class BetaFunctionShellTool` - - `:"gpt-5.6-luna"` + A tool that allows the model to execute shell commands. - - `:"gpt-5.4"` + - `class BetaCustomTool` - - `:"gpt-5.4-mini"` + 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) - - `:"gpt-5.4-nano"` + - `class BetaNamespaceTool` - - `:"gpt-5.4-mini-2026-03-17"` + Groups function/custom tools under a shared namespace. - - `:"gpt-5.4-nano-2026-03-17"` + - `class BetaToolSearchTool` - - `:"gpt-5.3-chat-latest"` + Hosted or BYOT tool search configuration for deferred tools. - - `:"gpt-5.2"` + - `class BetaWebSearchPreviewTool` - - `:"gpt-5.2-2025-12-11"` + 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.2-chat-latest"` + - `class BetaApplyPatchTool` - - `:"gpt-5.2-pro"` + Allows the assistant to create, delete, or update files using unified diffs. - - `:"gpt-5.2-pro-2025-12-11"` + - `top_logprobs: Integer` - - `:"gpt-5.1"` + 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. - - `:"gpt-5.1-2025-11-13"` + - `top_p: Float` - - `:"gpt-5.1-codex"` + 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. - - `:"gpt-5.1-mini"` + We generally recommend altering this or `temperature` but not both. - - `:"gpt-5.1-chat-latest"` + - `truncation: :auto | :disabled` - - `:"gpt-5"` + The truncation strategy to use for the model response. - - `:"gpt-5-mini"` + - `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. - - `:"gpt-5-nano"` + - `:auto` - - `:"gpt-5-2025-08-07"` + - `:disabled` - - `:"gpt-5-mini-2025-08-07"` + - `user: String` - - `:"gpt-5-nano-2025-08-07"` + 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). - - `:"gpt-5-chat-latest"` + - `class BetaResponseInjectEvent` - - `:"gpt-4.1"` + 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. - - `:"gpt-4.1-mini"` + - `input: Array[BetaResponseInputItem]` - - `:"gpt-4.1-nano"` + Input items to inject into the active response. - - `:"gpt-4.1-2025-04-14"` + - `class BetaEasyInputMessage` - - `:"gpt-4.1-mini-2025-04-14"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `:"gpt-4.1-nano-2025-04-14"` + - `class Message` - - `:"o4-mini"` + 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. - - `:"o4-mini-2025-04-16"` + - `class BetaResponseOutputMessage` - - `:o3` + An output message from the model. - - `:"o3-2025-04-16"` + - `class BetaResponseFileSearchToolCall` - - `:"o3-mini"` + 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. - - `:"o3-mini-2025-01-31"` + - `class BetaResponseComputerToolCall` - - `:o1` + 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. - - `:"o1-2024-12-17"` + - `class ComputerCallOutput` - - `:"o1-preview"` + The output of a computer tool call. - - `:"o1-preview-2024-09-12"` + - `class BetaResponseFunctionWebSearch` - - `:"o1-mini"` + 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. - - `:"o1-mini-2024-09-12"` + - `class BetaResponseFunctionToolCall` - - `:"gpt-4o"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:"gpt-4o-2024-11-20"` + - `class FunctionCallOutput` - - `:"gpt-4o-2024-08-06"` + The output of a function tool call. - - `:"gpt-4o-2024-05-13"` + - `class AgentMessage` - - `:"gpt-4o-audio-preview"` + A message routed between agents. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `class MultiAgentCall` - - `:"gpt-4o-audio-preview-2024-12-17"` + - `class MultiAgentCallOutput` - - `:"gpt-4o-audio-preview-2025-06-03"` + - `class ToolSearchCall` - - `:"gpt-4o-mini-audio-preview"` + - `class BetaResponseToolSearchOutputItemParam` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `class AdditionalTools` - - `:"gpt-4o-search-preview"` + - `class BetaResponseReasoningItem` - - `:"gpt-4o-mini-search-preview"` + 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). - - `:"gpt-4o-search-preview-2025-03-11"` + - `class BetaResponseCompactionItemParam` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:"chatgpt-4o-latest"` + - `class ImageGenerationCall` - - `:"codex-mini-latest"` + An image generation request made by the model. - - `:"gpt-4o-mini"` + - `class BetaResponseCodeInterpreterToolCall` - - `:"gpt-4o-mini-2024-07-18"` + A tool call to run code. - - `:"gpt-4-turbo"` + - `class LocalShellCall` - - `:"gpt-4-turbo-2024-04-09"` + A tool call to run a command on the local shell. - - `:"gpt-4-0125-preview"` + - `class LocalShellCallOutput` - - `:"gpt-4-turbo-preview"` + The output of a local shell tool call. - - `:"gpt-4-1106-preview"` + - `class ShellCall` - - `:"gpt-4-vision-preview"` + A tool representing a request to execute one or more shell commands. - - `:"gpt-4"` + - `class ShellCallOutput` - - `:"gpt-4-0314"` + The streamed output items emitted by a shell tool call. - - `:"gpt-4-0613"` + - `class ApplyPatchCall` - - `:"gpt-4-32k"` + A tool call representing a request to create, delete, or update files using diff patches. - - `:"gpt-4-32k-0314"` + - `class ApplyPatchCallOutput` - - `:"gpt-4-32k-0613"` + The streamed output emitted by an apply patch tool call. - - `:"gpt-3.5-turbo"` + - `class McpListTools` - - `:"gpt-3.5-turbo-16k"` + A list of tools available on an MCP server. - - `:"gpt-3.5-turbo-0301"` + - `class McpApprovalRequest` - - `:"gpt-3.5-turbo-0613"` + A request for human approval of a tool invocation. - - `:"gpt-3.5-turbo-1106"` + - `class McpApprovalResponse` - - `:"gpt-3.5-turbo-0125"` + A response to an MCP approval request. - - `:"gpt-3.5-turbo-16k-0613"` + - `class McpCall` - - `:"o1-pro"` + An invocation of a tool on an MCP server. - - `:"o1-pro-2025-03-19"` + - `class BetaResponseCustomToolCallOutput` - - `:"o3-pro"` + The output of a custom tool call from your code, being sent back to the model. - - `:"o3-pro-2025-06-10"` + - `class BetaResponseCustomToolCall` - - `:"o3-deep-research"` + A call to a custom tool created by the model. - - `:"o3-deep-research-2025-06-26"` + - `class CompactionTrigger` - - `:"o4-mini-deep-research"` + Compacts the current context. Must be the final input item. - - `:"o4-mini-deep-research-2025-06-26"` + - `class ItemReference` - - `:"computer-use-preview"` + An internal identifier for an item to reference. - - `:"computer-use-preview-2025-03-11"` + - `class Program` - - `:"gpt-5-codex"` + - `class ProgramOutput` - - `:"gpt-5-pro"` + - `response_id: String` - - `:"gpt-5-pro-2025-10-06"` + The ID of the active response that should receive the input. - - `:"gpt-5.1-codex-max"` + - `type: :"response.inject"` - - `String = String` + The event discriminator. Always `response.inject`. - - `object: :response` + - `:"response.inject"` - The object type of this resource - always set to `response`. +### Beta Responses Server Event - - `:response` +- `BetaResponsesServerEvent = BetaResponseAudioDeltaEvent | BetaResponseAudioDoneEvent | BetaResponseAudioTranscriptDeltaEvent | 52 more` - - `output: Array[BetaResponseOutputItem]` + Server events emitted by the Responses WebSocket server. - An array of content items generated by the model. + - `class BetaResponseAudioDeltaEvent` - - 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. + Emitted when there is a partial audio response. - - `class BetaResponseOutputMessage` + - `delta: String` - An output message from the model. + A chunk of Base64 encoded response audio bytes. - - `class BetaResponseFileSearchToolCall` + - `sequence_number: Integer` - 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 sequence number for this chunk of the stream response. - - `class BetaResponseFunctionToolCall` + - `type: :"response.audio.delta"` - 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 the event. Always `response.audio.delta`. - - `class BetaResponseFunctionToolCallOutputItem` + - `:"response.audio.delta"` - - `id: String` + - `agent: Agent{ agent_name}` - The unique ID of the function call tool output. + The agent that owns this multi-agent streaming event. - - `call_id: String` + - `agent_name: String` - The unique ID of the function tool call generated by the model. + The canonical name of the agent that produced this item. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class BetaResponseAudioDoneEvent` - The output from the function call generated by your code. - Can be a string or an list of output content. + Emitted when the audio response is complete. - - `String = String` + - `sequence_number: Integer` - A string of the output of the function call. + The sequence number of the delta. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `type: :"response.audio.done"` - Text, image, or file output of the function call. + The type of the event. Always `response.audio.done`. - - `class BetaResponseInputText` + - `:"response.audio.done"` - A text input to the model. + - `agent: Agent{ agent_name}` - - `class BetaResponseInputImage` + The agent that owns this multi-agent streaming event. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent_name: String` - - `class BetaResponseInputFile` + The canonical name of the agent that produced this item. - A file input to the model. + - `class BetaResponseAudioTranscriptDeltaEvent` - - `status: :in_progress | :completed | :incomplete` + Emitted when there is a partial transcript of audio. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `delta: String` - - `:in_progress` + The partial transcript of the audio response. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of this event. - - `type: :function_call_output` + - `type: :"response.audio.transcript.delta"` - The type of the function tool call output. Always `function_call_output`. + The type of the event. Always `response.audio.transcript.delta`. - - `:function_call_output` + - `:"response.audio.transcript.delta"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseAudioTranscriptDoneEvent` - The execution context that produced this tool call. + Emitted when the full audio transcript is completed. - - `class Direct` + - `sequence_number: Integer` - - `type: :direct` + The sequence number of this event. - The caller type. Always `direct`. + - `type: :"response.audio.transcript.done"` - - `:direct` + The type of the event. Always `response.audio.transcript.done`. - - `class Program` + - `:"response.audio.transcript.done"` - - `caller_id: String` + - `agent: Agent{ 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` + - `class BetaResponseCodeInterpreterCallCodeDeltaEvent` - - `created_by: String` + Emitted when a partial code snippet is streamed by the code interpreter. - The identifier of the actor that created the item. + - `delta: String` - - `class AgentMessage` + The partial code snippet being streamed by the code interpreter. - - `id: String` + - `item_id: String` - The unique ID of the agent message. + The unique identifier of the code interpreter tool call item. - - `author: String` + - `output_index: Integer` - The sending agent identity. + The index of the output item in the response for which the code is being streamed. - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `sequence_number: Integer` - Encrypted content sent between agents. + The sequence number of this event, used to order streaming events. - - `class BetaResponseInputText` + - `type: :"response.code_interpreter_call_code.delta"` - A text input to the model. + The type of the event. Always `response.code_interpreter_call_code.delta`. - - `class BetaResponseOutputText` + - `:"response.code_interpreter_call_code.delta"` - A text output from the model. + - `agent: Agent{ agent_name}` - - `class Text` + The agent that owns this multi-agent streaming event. - A text content. + - `agent_name: String` - - `text: String` + The canonical name of the agent that produced this item. - - `type: :text` + - `class BetaResponseCodeInterpreterCallCodeDoneEvent` - - `:text` + Emitted when the code snippet is finalized by the code interpreter. - - `class SummaryText` + - `code: String` - A summary text from the model. + The final code snippet output by the code interpreter. - - `text: String` + - `item_id: String` - A summary of the reasoning output from the model so far. + The unique identifier of the code interpreter tool call item. - - `type: :summary_text` + - `output_index: Integer` - The type of the object. Always `summary_text`. + The index of the output item in the response for which the code is finalized. - - `:summary_text` + - `sequence_number: Integer` - - `class ReasoningText` + The sequence number of this event, used to order streaming events. - Reasoning text from the model. + - `type: :"response.code_interpreter_call_code.done"` - - `text: String` + The type of the event. Always `response.code_interpreter_call_code.done`. - The reasoning text from the model. + - `:"response.code_interpreter_call_code.done"` - - `type: :reasoning_text` + - `agent: Agent{ agent_name}` - The type of the reasoning text. Always `reasoning_text`. + The agent that owns this multi-agent streaming event. - - `:reasoning_text` + - `agent_name: String` - - `class BetaResponseOutputRefusal` + The canonical name of the agent that produced this item. - A refusal from the model. + - `class BetaResponseCodeInterpreterCallCompletedEvent` - - `class BetaResponseInputImage` + Emitted when the code interpreter call is completed. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `item_id: String` - - `class ComputerScreenshot` + The unique identifier of the code interpreter tool call item. - A screenshot of a computer. + - `output_index: Integer` - - `detail: :low | :high | :auto | :original` + The index of the output item in the response for which the code interpreter call is completed. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `sequence_number: Integer` - - `:low` + The sequence number of this event, used to order streaming events. - - `:high` + - `type: :"response.code_interpreter_call.completed"` - - `:auto` + The type of the event. Always `response.code_interpreter_call.completed`. - - `:original` + - `:"response.code_interpreter_call.completed"` - - `file_id: String` + - `agent: Agent{ agent_name}` - The identifier of an uploaded file that contains the screenshot. + The agent that owns this multi-agent streaming event. - - `image_url: String` + - `agent_name: String` - The URL of the screenshot image. + The canonical name of the agent that produced this item. - - `type: :computer_screenshot` + - `class BetaResponseCodeInterpreterCallInProgressEvent` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Emitted when a code interpreter call is in progress. - - `:computer_screenshot` + - `item_id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The unique identifier of the code interpreter tool call 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. + - `output_index: Integer` - - `mode: :explicit` + The index of the output item in the response for which the code interpreter call is in progress. - The breakpoint mode. Always `explicit`. + - `sequence_number: Integer` - - `:explicit` + The sequence number of this event, used to order streaming events. + + - `type: :"response.code_interpreter_call.in_progress"` + + The type of the event. Always `response.code_interpreter_call.in_progress`. + + - `:"response.code_interpreter_call.in_progress"` + + - `agent: Agent{ agent_name}` - - `class BetaResponseInputFile` + The agent that owns this multi-agent streaming event. - A file input to the model. + - `agent_name: String` - - `class EncryptedContent` + The canonical name of the agent that produced this item. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `class BetaResponseCodeInterpreterCallInterpretingEvent` - - `encrypted_content: String` + Emitted when the code interpreter is actively interpreting the code snippet. - Opaque encrypted content. + - `item_id: String` - - `type: :encrypted_content` + The unique identifier of the code interpreter tool call item. - The type of the input item. Always `encrypted_content`. + - `output_index: Integer` - - `:encrypted_content` + The index of the output item in the response for which the code interpreter is interpreting code. - - `recipient: String` + - `sequence_number: Integer` - The destination agent identity. + The sequence number of this event, used to order streaming events. - - `type: :agent_message` + - `type: :"response.code_interpreter_call.interpreting"` - The type of the item. Always `agent_message`. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `:agent_message` + - `:"response.code_interpreter_call.interpreting"` - `agent: Agent{ 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. - - `class MultiAgentCall` + - `class BetaResponseCompletedEvent` + + Emitted when the model response is complete. + + - `response: BetaResponse` + + Properties of the completed response. - `id: String` - The unique ID of the multi-agent call item. + Unique identifier for this Response. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `created_at: Float` - The multi-agent action to execute. + Unix timestamp (in seconds) of when this Response was created. - - `:spawn_agent` + - `error: BetaResponseError` - - `:interrupt_agent` + An error object returned when the model fails to generate a Response. - - `:list_agents` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` - - `:send_message` + The error code for the response. - - `:followup_task` + - `:server_error` - - `:wait_agent` + - `:rate_limit_exceeded` - - `arguments: String` + - `:invalid_prompt` - The JSON string of arguments generated for the action. + - `:bio_policy` - - `call_id: String` + - `:vector_store_timeout` - The unique ID linking this call to its output. + - `:invalid_image` - - `type: :multi_agent_call` + - `:invalid_image_format` - The type of the multi-agent call. Always `multi_agent_call`. + - `:invalid_base64_image` - - `:multi_agent_call` + - `:invalid_image_url` - - `agent: Agent{ 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` - - `class MultiAgentCallOutput` + - `:invalid_image_mode` - - `id: String` + - `:image_file_too_large` - The unique ID of the multi-agent call output item. + - `:unsupported_image_media_type` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:empty_image_file` - The multi-agent action that produced this result. + - `:failed_to_download_image` - - `:spawn_agent` + - `:image_file_not_found` - - `:interrupt_agent` + - `message: String` - - `:list_agents` + A human-readable description of the error. - - `:send_message` + - `incomplete_details: IncompleteDetails{ reason}` - - `:followup_task` + Details about why the response is incomplete. - - `:wait_agent` + - `reason: :max_output_tokens | :content_filter` - - `call_id: String` + The reason why the response is incomplete. - The unique ID of the multi-agent call. + - `:max_output_tokens` - - `output: Array[BetaResponseOutputText]` + - `:content_filter` - Text output returned by the multi-agent action. + - `instructions: String | Array[BetaResponseInputItem]` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + A system (or developer) message inserted into the model's context. - The annotations of the text output. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `text: String` + - `String = String` - The text output from the model. + A text input to the model, equivalent to a text input with the + `developer` role. - - `type: :output_text` + - `InputItemList = Array[BetaResponseInputItem]` - The type of the output text. Always `output_text`. + A list of one or many input items to the model, containing + different content types. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `class BetaEasyInputMessage` - - `type: :multi_agent_call_output` + 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 type of the multi-agent result. Always `multi_agent_call_output`. + - `content: String | BetaResponseInputMessageContentList` - - `:multi_agent_call_output` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `agent: Agent{ agent_name}` + - `String = String` - The agent that produced this item. + A text input to the model. - - `agent_name: String` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - The canonical name of the agent that produced this item. + A list of one or many input items to the model, containing different content + types. - - `class BetaResponseFunctionWebSearch` + - `class BetaResponseInputText` - 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 text input to the model. - - `class BetaResponseComputerToolCall` + - `text: 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. + The text input to the model. - - `class BetaResponseComputerToolCallOutputItem` + - `type: :input_text` - - `id: String` + The type of the input item. Always `input_text`. - The unique ID of the computer call tool output. + - `:input_text` - - `call_id: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The ID of the computer tool call that produced the output. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `mode: :explicit` - A computer screenshot image used with the computer use tool. + The breakpoint mode. Always `explicit`. - - `status: :completed | :incomplete | :failed | :in_progress` + - `:explicit` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaResponseInputImage` - - `:completed` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:incomplete` + - `detail: :low | :high | :auto | :original` - - `:failed` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `:in_progress` + - `:low` - - `type: :computer_call_output` + - `:high` - The type of the computer tool call output. Always `computer_call_output`. + - `:auto` - - `:computer_call_output` + - `:original` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `type: :input_image` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of the input item. Always `input_image`. - - `id: String` + - `:input_image` - The ID of the pending safety check. + - `file_id: String` - - `code: String` + The ID of the file to be sent to the model. - The type of the pending safety check. + - `image_url: String` - - `message: String` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Details about the pending safety check. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `agent: Agent{ 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` - - `created_by: String` + - `class BetaResponseInputFile` - The identifier of the actor that created the item. + A file input to the model. - - `class BetaResponseReasoningItem` + - `type: :input_file` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The type of the input item. Always `input_file`. - - `class Program` + - `:input_file` - - `id: String` + - `detail: :auto | :low | :high` - The unique ID of the program 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 stable call ID of the program item. + - `:low` - - `code: String` + - `:high` - The JavaScript source executed by programmatic tool calling. + - `file_data: String` - - `fingerprint: String` + The content of the file to be sent to the model. - Opaque program replay fingerprint that must be round-tripped. + - `file_id: String` - - `type: :program` + The ID of the file to be sent to the model. - The type of the item. Always `program`. + - `file_url: String` - - `:program` + The URL of the file to be sent to the model. - - `agent: Agent{ agent_name}` + - `filename: String` - The agent that produced this item. + The name of the file to be sent to the model. - - `agent_name: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `class ProgramOutput` + - `mode: :explicit` - - `id: String` + The breakpoint mode. Always `explicit`. - The unique ID of the program output item. + - `:explicit` - - `call_id: String` + - `role: :user | :assistant | :system | :developer` - The call ID of the program item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `result: String` + - `:user` - The result produced by the program item. + - `:assistant` - - `status: :completed | :incomplete` + - `:system` - The terminal status of the program output item. + - `:developer` - - `:completed` + - `phase: :commentary | :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. - - `type: :program_output` + - `:commentary` - The type of the item. Always `program_output`. + - `:final_answer` - - `:program_output` + - `type: :message` - - `agent: Agent{ agent_name}` + The type of the message input. Always `message`. - The agent that produced this item. + - `:message` - - `agent_name: String` + - `class Message` - The canonical name of the agent that produced this item. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `class BetaResponseToolSearchCall` + - `content: BetaResponseInputMessageContentList` - - `id: String` + A list of one or many input items to the model, containing different content + types. - The unique ID of the tool search call item. + - `role: :user | :system | :developer` - - `arguments: untyped` + The role of the message input. One of `user`, `system`, or `developer`. - Arguments used for the tool search call. + - `:user` - - `call_id: String` + - `:system` - The unique ID of the tool search call generated by the model. + - `:developer` - - `execution: :server | :client` + - `agent: Agent{ 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 | :completed | :incomplete` - The status of the tool search call item that was recorded. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -121786,237 +134590,242 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :tool_search_call` + - `type: :message` - The type of the item. Always `tool_search_call`. + The type of the message input. Always set to `message`. - - `:tool_search_call` + - `:message` - - `agent: Agent{ agent_name}` + - `class BetaResponseOutputMessage` - The agent that produced this item. + An output message from the model. - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The unique ID of the output message. - - `created_by: String` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - The identifier of the actor that created the item. + The content of the output message. - - `class BetaResponseToolSearchOutputItem` + - `class BetaResponseOutputText` - - `id: String` + A text output from the model. - The unique ID of the tool search output item. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `call_id: String` + The annotations of the text output. - The unique ID of the tool search call generated by the model. + - `class FileCitation` - - `execution: :server | :client` + A citation to a file. - Whether tool search was executed by the server or by the client. + - `file_id: String` - - `:server` + The ID of the file. - - `:client` + - `filename: String` - - `status: :in_progress | :completed | :incomplete` + The filename of the file cited. - The status of the tool search output item that was recorded. + - `index: Integer` - - `:in_progress` + The index of the file in the list of files. - - `:completed` + - `type: :file_citation` - - `:incomplete` + The type of the file citation. Always `file_citation`. - - `tools: Array[BetaTool]` + - `:file_citation` - The loaded tool definitions returned by tool search. + - `class URLCitation` - - `class BetaFunctionTool` + A citation for a web resource used to generate a model response. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `end_index: Integer` - - `class BetaFileSearchTool` + The index of the last character of the URL citation in the message. - 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). + - `start_index: Integer` - - `class BetaComputerTool` + The index of the first character of the URL citation in the message. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `title: String` - - `class BetaComputerUsePreviewTool` + The title of the web resource. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :url_citation` - - `class BetaWebSearchTool` + The type of the URL citation. Always `url_citation`. - 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). + - `:url_citation` - - `class Mcp` + - `url: 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 URL of the web resource. - - `class CodeInterpreter` + - `class ContainerFileCitation` - A tool that runs Python code to help generate a response to a prompt. + A citation for a container file used to generate a model response. - - `class ProgrammaticToolCalling` + - `container_id: String` - - `class ImageGeneration` + The ID of the container file. - A tool that generates images using the GPT image models. + - `end_index: Integer` - - `class LocalShell` + The index of the last character of the container file citation in the message. - A tool that allows the model to execute shell commands in a local environment. + - `file_id: String` - - `class BetaFunctionShellTool` + The ID of the file. - A tool that allows the model to execute shell commands. + - `filename: String` - - `class BetaCustomTool` + The filename of the container file cited. - 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) + - `start_index: Integer` - - `class BetaNamespaceTool` + The index of the first character of the container file citation in the message. - Groups function/custom tools under a shared namespace. + - `type: :container_file_citation` - - `class BetaToolSearchTool` + The type of the container file citation. Always `container_file_citation`. - Hosted or BYOT tool search configuration for deferred tools. + - `:container_file_citation` - - `class BetaWebSearchPreviewTool` + - `class FilePath` - 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 path to a file. - - `class BetaApplyPatchTool` + - `file_id: String` - Allows the assistant to create, delete, or update files using unified diffs. + The ID of the file. - - `type: :tool_search_output` + - `index: Integer` - The type of the item. Always `tool_search_output`. + The index of the file in the list of files. - - `:tool_search_output` + - `type: :file_path` - - `agent: Agent{ agent_name}` + The type of the file path. Always `file_path`. - The agent that produced this item. + - `:file_path` - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + The text output from the model. - - `created_by: String` + - `type: :output_text` - The identifier of the actor that created the item. + The type of the output text. Always `output_text`. - - `class AdditionalTools` + - `:output_text` - - `id: String` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - The unique ID of the additional tools item. + - `token: String` - - `role: :unknown | :user | :assistant | 5 more` + - `bytes: Array[Integer]` - The role that provided the additional tools. + - `logprob: Float` - - `:unknown` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `:user` + - `token: String` - - `:assistant` + - `bytes: Array[Integer]` - - `:system` + - `logprob: Float` - - `:critic` + - `class BetaResponseOutputRefusal` - - `:discriminator` + A refusal from the model. - - `:developer` + - `refusal: String` - - `:tool` + The refusal explanation from the model. - - `tools: Array[BetaTool]` + - `type: :refusal` - The additional tool definitions made available at this item. + The type of the refusal. Always `refusal`. - - `class BetaFunctionTool` + - `:refusal` - 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). + - `role: :assistant` - - `class BetaFileSearchTool` + The role of the output message. Always `assistant`. - 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). + - `:assistant` - - `class BetaComputerTool` + - `status: :in_progress | :completed | :incomplete` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class BetaComputerUsePreviewTool` + - `: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` - - `class BetaWebSearchTool` + - `:incomplete` - 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: :message` - - `class Mcp` + The type of the output message. Always `message`. - 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` - - `class CodeInterpreter` + - `agent: Agent{ agent_name}` - A tool that runs Python code to help generate a response to a prompt. + The agent that produced this item. - - `class ProgrammaticToolCalling` + - `agent_name: String` - - `class ImageGeneration` + The canonical name of the agent that produced this item. - A tool that generates images using the GPT image models. + - `phase: :commentary | :final_answer` - - `class LocalShell` + 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 tool that allows the model to execute shell commands in a local environment. + - `:commentary` - - `class BetaFunctionShellTool` + - `:final_answer` - A tool that allows the model to execute shell commands. + - `class BetaResponseFileSearchToolCall` - - `class BetaCustomTool` + 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 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` - - `class BetaNamespaceTool` + The unique ID of the file search tool call. - Groups function/custom tools under a shared namespace. + - `queries: Array[String]` - - `class BetaToolSearchTool` + The queries used to search for files. - Hosted or BYOT tool search configuration for deferred tools. + - `status: :in_progress | :searching | :completed | 2 more` - - `class BetaWebSearchPreviewTool` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `:in_progress` - - `class BetaApplyPatchTool` + - `:searching` - Allows the assistant to create, delete, or update files using unified diffs. + - `:completed` - - `type: :additional_tools` + - `:incomplete` - The type of the item. Always `additional_tools`. + - `:failed` - - `:additional_tools` + - `type: :file_search_call` + + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` - `agent: Agent{ agent_name}` @@ -122026,525 +134835,531 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The results of the file search tool call. - - `id: String` + - `attributes: Hash[Symbol, String | Float | bool]` - The unique ID of the compaction item. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `encrypted_content: String` + - `String = String` - The encrypted content that was produced by compaction. + - `Float = Float` - - `type: :compaction` + - `UnionMember2 = bool` - The type of the item. Always `compaction`. + - `file_id: String` - - `:compaction` + The unique ID of the file. - - `agent: Agent{ agent_name}` + - `filename: String` - The agent that produced this item. + The name of the file. - - `agent_name: String` + - `score: Float` - The canonical name of the agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `created_by: String` + - `text: String` - The identifier of the actor that created the item. + The text that was retrieved from the file. - - `class ImageGenerationCall` + - `class BetaResponseComputerToolCall` - An image generation request made by the model. + 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 image generation call. + The unique ID of the computer call. - - `result: String` + - `call_id: String` - The generated image encoded in base64. + An identifier used when responding to the tool call with output. - - `status: :in_progress | :completed | :generating | :failed` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - The status of the image generation call. + The pending safety checks for the computer call. - - `:in_progress` + - `id: String` - - `:completed` + The ID of the pending safety check. - - `:generating` + - `code: String` - - `:failed` + The type of the pending safety check. - - `type: :image_generation_call` + - `message: String` - The type of the image generation call. Always `image_generation_call`. + Details about the pending safety check. - - `:image_generation_call` + - `status: :in_progress | :completed | :incomplete` - - `agent: Agent{ 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` - - `class BetaResponseCodeInterpreterToolCall` + - `type: :computer_call` - A tool call to run code. + The type of the computer call. Always `computer_call`. - - `class LocalShellCall` + - `:computer_call` - A tool call to run a command on the local shell. + - `action: BetaComputerAction` - - `id: String` + A click action. - The unique ID of the local shell call. + - `class Click` - - `action: Action{ command, env, type, 3 more}` + A click action. - Execute a shell command on the server. + - `button: :left | :right | :wheel | 2 more` - - `command: Array[String]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The command to run. + - `:left` - - `env: Hash[Symbol, String]` + - `:right` - Environment variables to set for the command. + - `:wheel` - - `type: :exec` + - `:back` - The type of the local shell action. Always `exec`. + - `:forward` - - `:exec` + - `type: :click` - - `timeout_ms: Integer` + Specifies the event type. For a click action, this property is always `click`. - Optional timeout in milliseconds for the command. + - `:click` - - `user: String` + - `x: Integer` - Optional user to run the command as. + The x-coordinate where the click occurred. - - `working_directory: String` + - `y_: Integer` - Optional working directory to run the command in. + The y-coordinate where the click occurred. - - `call_id: String` + - `keys: Array[String]` - The unique ID of the local shell tool call generated by the model. + The keys being held while clicking. - - `status: :in_progress | :completed | :incomplete` + - `class DoubleClick` - The status of the local shell call. + A double click action. - - `:in_progress` + - `keys: Array[String]` - - `:completed` + The keys being held while double-clicking. - - `:incomplete` + - `type: :double_click` - - `type: :local_shell_call` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The type of the local shell call. Always `local_shell_call`. + - `:double_click` - - `:local_shell_call` + - `x: Integer` - - `agent: Agent{ agent_name}` + The x-coordinate where the double click occurred. - The agent that produced this item. + - `y_: Integer` - - `agent_name: String` + The y-coordinate where the double click occurred. - The canonical name of the agent that produced this item. + - `class Drag` - - `class LocalShellCallOutput` + A drag action. - The output of a local shell tool call. + - `path: Array[Path{ x, y_}]` - - `id: String` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The unique ID of the local shell tool call generated by the model. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `output: String` + - `x: Integer` - A JSON string of the output of the local shell tool call. + The x-coordinate. - - `type: :local_shell_call_output` + - `y_: Integer` - The type of the local shell tool call output. Always `local_shell_call_output`. + The y-coordinate. - - `:local_shell_call_output` + - `type: :drag` - - `agent: Agent{ agent_name}` + Specifies the event type. For a drag action, this property is always set to `drag`. - The agent that produced this item. + - `:drag` - - `agent_name: String` + - `keys: Array[String]` - The canonical name of the agent that produced this item. + The keys being held while dragging the mouse. - - `status: :in_progress | :completed | :incomplete` + - `class Keypress` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A collection of keypresses the model would like to perform. - - `:in_progress` + - `keys: Array[String]` - - `:completed` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `:incomplete` + - `type: :keypress` - - `class BetaResponseFunctionShellToolCall` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - A tool call that executes one or more shell commands in a managed environment. + - `:keypress` - - `id: String` + - `class Move` - The unique ID of the shell tool call. Populated when this item is returned via API. + A mouse move action. - - `action: Action{ commands, max_output_length, timeout_ms}` + - `type: :move` - The shell commands and limits that describe how to run the tool call. + Specifies the event type. For a move action, this property is always set to `move`. - - `commands: Array[String]` + - `:move` - - `max_output_length: Integer` + - `x: Integer` - Optional maximum number of characters to return from each command. + The x-coordinate to move to. - - `timeout_ms: Integer` + - `y_: Integer` - Optional timeout in milliseconds for the commands. + The y-coordinate to move to. - - `call_id: String` + - `keys: Array[String]` - The unique ID of the shell tool call generated by the model. + The keys being held while moving the mouse. - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `class Screenshot` - Represents the use of a local environment to perform shell actions. + A screenshot action. - - `class BetaResponseLocalEnvironment` + - `type: :screenshot` - Represents the use of a local environment to perform shell actions. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: :local` + - `:screenshot` - The environment type. Always `local`. + - `class Scroll` - - `:local` + A scroll action. - - `class BetaResponseContainerReference` + - `scroll_x: Integer` - Represents a container created with /v1/containers. + The horizontal scroll distance. - - `container_id: String` + - `scroll_y: Integer` - - `type: :container_reference` + The vertical scroll distance. - The environment type. Always `container_reference`. + - `type: :scroll` - - `:container_reference` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `status: :in_progress | :completed | :incomplete` + - `:scroll` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `x: Integer` - - `:in_progress` + The x-coordinate where the scroll occurred. - - `:completed` + - `y_: Integer` - - `:incomplete` + The y-coordinate where the scroll occurred. - - `type: :shell_call` + - `keys: Array[String]` - The type of the item. Always `shell_call`. + The keys being held while scrolling. - - `:shell_call` + - `class Type` - - `agent: Agent{ 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_: Direct{ type} | Program{ 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` - - `class Direct` + - `class Wait` - - `type: :direct` + A wait action. - - `:direct` + - `type: :wait` - - `class Program` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `caller_id: String` + - `:wait` - The call ID of the program item that produced this tool call. + - `actions: BetaComputerActionList` - - `type: :program` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `:program` + - `class Click` - - `created_by: String` + A click action. - The ID of the entity that created this tool call. + - `class DoubleClick` - - `class BetaResponseFunctionShellToolCallOutput` + A double click action. - The output of a shell tool call that was emitted. + - `class Drag` - - `id: String` + A drag action. - The unique ID of the shell call output. Populated when this item is returned via API. + - `class Keypress` - - `call_id: String` + A collection of keypresses the model would like to perform. - The unique ID of the shell tool call generated by the model. + - `class Move` - - `max_output_length: Integer` + A mouse move action. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class Screenshot` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + A screenshot action. - An array of shell call output contents + - `class Scroll` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + A scroll action. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `class Type` - - `class Timeout` + An action to type in text. - Indicates that the shell call exceeded its configured time limit. + - `class Wait` - - `type: :timeout` + A wait action. - The outcome type. Always `timeout`. + - `agent: Agent{ agent_name}` - - `:timeout` + The agent that produced this item. - - `class Exit` + - `agent_name: String` - Indicates that the shell commands finished and returned an exit code. + The canonical name of the agent that produced this item. - - `exit_code: Integer` + - `class ComputerCallOutput` - Exit code from the shell process. + The output of a computer tool call. - - `type: :exit` + - `call_id: String` - The outcome type. Always `exit`. + The ID of the computer tool call that produced the output. - - `:exit` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `stderr: String` + A computer screenshot image used with the computer use tool. - The standard error output that was captured. + - `type: :computer_screenshot` - - `stdout: String` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The standard output that was captured. + - `:computer_screenshot` - - `created_by: String` + - `file_id: String` - The identifier of the actor that created the item. + The identifier of an uploaded file that contains the screenshot. - - `status: :in_progress | :completed | :incomplete` + - `image_url: String` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The URL of the screenshot image. - - `:in_progress` + - `type: :computer_call_output` - - `:completed` + The type of the computer tool call output. Always `computer_call_output`. - - `:incomplete` + - `:computer_call_output` - - `type: :shell_call_output` + - `id: String` - The type of the shell call output. Always `shell_call_output`. + The ID of the computer tool call output. - - `:shell_call_output` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `agent: Agent{ 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: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The type of the pending safety check. - The execution context that produced this tool call. + - `message: String` - - `class Direct` + Details about the pending safety check. - - `type: :direct` + - `agent: Agent{ agent_name}` - - `:direct` + The agent that produced this item. - - `class Program` + - `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. + - `status: :in_progress | :completed | :incomplete` - - `type: :program` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `:program` + - `:in_progress` - - `created_by: String` + - `:completed` - The identifier of the actor that created the item. + - `:incomplete` - - `class BetaResponseApplyPatchToolCall` + - `class BetaResponseFunctionWebSearch` - A tool call that applies file diffs by creating, deleting, or updating files. + 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 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: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class CreateFile` + The unique ID of the web search tool call. - Instruction describing how to create a file via the apply_patch tool. + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - - `diff: 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). - Diff to apply. + - `class Search` - - `path: String` + Action type "search" - Performs a web search query. - Path of the file to create. + - `type: :search` - - `type: :create_file` + The action type. - Create a new file with the provided diff. + - `:search` - - `:create_file` + - `queries: Array[String]` - - `class DeleteFile` + The search queries. - Instruction describing how to delete a file via the apply_patch tool. + - `query: String` - - `path: String` + The search query. - Path of the file to delete. + - `sources: Array[Source{ type, url}]` - - `type: :delete_file` + The sources used in the search. - Delete the specified file. + - `type: :url` - - `:delete_file` + The type of source. Always `url`. - - `class UpdateFile` + - `:url` - Instruction describing how to update a file via the apply_patch tool. + - `url: String` - - `diff: String` + The URL of the source. - Diff to apply. + - `class OpenPage` - - `path: String` + Action type "open_page" - Opens a specific URL from search results. - Path of the file to update. + - `type: :open_page` - - `type: :update_file` + The action type. - Update an existing file with the provided diff. + - `:open_page` - - `:update_file` + - `url: String` - - `status: :in_progress | :completed` + The URL opened by the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `class FindInPage` - - `:in_progress` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `:completed` + - `pattern: String` - - `type: :apply_patch_call` + The pattern or text to search for within the page. - The type of the item. Always `apply_patch_call`. + - `type: :find_in_page` - - `:apply_patch_call` + The action type. - - `agent: Agent{ agent_name}` + - `:find_in_page` - The agent that produced this item. + - `url: String` - - `agent_name: String` + The URL of the page searched for the pattern. - The canonical name of the agent that produced this item. + - `status: :in_progress | :searching | :completed | :failed` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The status of the web search tool call. - The execution context that produced this tool call. + - `:in_progress` - - `class Direct` + - `:searching` - - `type: :direct` + - `:completed` - - `:direct` + - `:failed` - - `class Program` + - `type: :web_search_call` - - `caller_id: String` + The type of the web search tool call. Always `web_search_call`. - The call ID of the program item that produced this tool call. + - `:web_search_call` - - `type: :program` + - `agent: Agent{ agent_name}` - - `:program` + The agent that produced this item. - - `created_by: String` + - `agent_name: String` - The ID of the entity that created this tool call. + The canonical name of the agent that produced this item. - - `class BetaResponseApplyPatchToolCallOutput` + - `class BetaResponseFunctionToolCall` - The output emitted by an apply patch tool call. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/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 | :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: String` - - `:apply_patch_call_output` + The unique ID of the function tool call. - `agent: Agent{ agent_name}` @@ -122574,180 +135389,160 @@ puts(beta_compacted_response) - `:program` - - `created_by: String` - - The ID of the entity that created this tool call output. - - - `output: String` - - Optional textual output returned by the apply patch tool. + - `namespace: String` - - `class McpCall` + The namespace of the function to run. - An invocation of a tool on an MCP server. + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The unique ID of the tool call. + - `:in_progress` - - `arguments: String` + - `:completed` - A JSON string of the arguments passed to the tool. + - `:incomplete` - - `name: String` + - `class FunctionCallOutput` - The name of the tool that was run. + The output of a function tool call. - - `server_label: String` + - `call_id: String` - The label of the MCP server running the tool. + The unique ID of the function tool call generated by the model. - - `type: :mcp_call` + - `output: String | BetaResponseFunctionCallOutputItemList` - The type of the item. Always `mcp_call`. + Text, image, or file output of the function tool call. - - `:mcp_call` + - `String = String` - - `agent: Agent{ agent_name}` + A JSON string of the output of the function tool call. - The agent that produced this item. + - `BetaResponseFunctionCallOutputItemList = Array[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. + - `class BetaResponseInputTextContent` - - `approval_request_id: String` + A text input to the model. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `text: String` - - `error: String` + The text input to the model. - The error from the tool call, if any. + - `type: :input_text` - - `output: String` + The type of the input item. Always `input_text`. - The output from the tool call. + - `:input_text` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `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` - - `:completed` + The breakpoint mode. Always `explicit`. - - `:incomplete` + - `:explicit` - - `:calling` + - `class BetaResponseInputImageContent` - - `:failed` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class McpListTools` + - `type: :input_image` - A list of tools available on an MCP server. + The type of the input item. Always `input_image`. - - `id: String` + - `:input_image` - The unique ID of the list. + - `detail: :low | :high | :auto | :original` - - `server_label: String` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The label of the MCP server. + - `:low` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `:high` - The tools available on the server. + - `:auto` - - `input_schema: untyped` + - `:original` - The JSON schema describing the tool's input. + - `file_id: String` - - `name: String` + The ID of the file to be sent to the model. - The name of the tool. + - `image_url: String` - - `annotations: untyped` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Additional annotations about the tool. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `description: String` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The description of the tool. + - `mode: :explicit` - - `type: :mcp_list_tools` + The breakpoint mode. Always `explicit`. - The type of the item. Always `mcp_list_tools`. + - `:explicit` - - `:mcp_list_tools` + - `class BetaResponseInputFileContent` - - `agent: Agent{ 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` - - `error: String` + - `detail: :auto | :low | :high` - Error message if the server could not list tools. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class McpApprovalRequest` + - `:auto` - A request for human approval of a tool invocation. + - `:low` - - `id: String` + - `:high` - The unique ID of the approval request. + - `file_data: String` - - `arguments: String` + The base64-encoded data of the file to be sent to the model. - A JSON string of arguments for the tool. + - `file_id: String` - - `name: String` + The ID of the file to be sent to the model. - The name of the tool to run. + - `file_url: String` - - `server_label: String` + The URL of the file to be sent to the model. - The label of the MCP server making the request. + - `filename: String` - - `type: :mcp_approval_request` + The name of the file to be sent to the model. - The type of the item. Always `mcp_approval_request`. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `: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. - - `agent: Agent{ 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. + - `type: :function_call_output` - - `class McpApprovalResponse` + The type of the function tool call output. Always `function_call_output`. - A response to an MCP approval request. + - `:function_call_output` - `id: String` - The unique ID of the approval response - - - `approval_request_id: String` - - The ID of the approval request being answered. - - - `approve: bool` - - Whether the request was approved. - - - `type: :mcp_approval_response` - - The type of the item. Always `mcp_approval_response`. - - - `:mcp_approval_response` + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -122757,26 +135552,33 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `reason: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Optional reason for the decision. + The execution context that produced this tool call. - - `class BetaResponseCustomToolCall` + - `class Direct` - A call to a custom tool created by the model. + - `type: :direct` - - `class BetaResponseCustomToolCallOutputItem` + The caller type. Always `direct`. - The output of a custom tool call from your code, being sent back to the model. + - `:direct` - - `id: String` + - `class Program` - The unique ID of the custom tool call output item. + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` - `status: :in_progress | :completed | :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` @@ -122784,1784 +135586,1717 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` + - `class AgentMessage` - The identifier of the actor that created the item. + A message routed between agents. - - `parallel_tool_calls: bool` + - `author: String` - Whether to allow the model to run tool calls in parallel. + The sending agent identity. - - `temperature: Float` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, 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. - We generally recommend altering this or `top_p` but not both. + Plaintext, image, or encrypted content sent between agents. - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `class BetaResponseInputTextContent` - 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. + A text input to the model. - - `BetaToolChoiceOptions = :none | :auto | :required` + - `class BetaResponseInputImageContent` - Controls which (if any) tool is called by the model. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `none` means the model will not call any tool and instead generates a message. + - `class EncryptedContent` - `auto` means the model can pick between generating a message or calling one or - more tools. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - `required` means the model must call one or more tools. + - `encrypted_content: String` - - `:none` + Opaque encrypted content. - - `:auto` + - `type: :encrypted_content` - - `:required` + The type of the input item. Always `encrypted_content`. - - `class BetaToolChoiceAllowed` + - `:encrypted_content` - Constrains the tools available to the model to a pre-defined set. + - `recipient: String` - - `mode: :auto | :required` + The destination agent identity. - Constrains the tools available to the model to a pre-defined set. + - `type: :agent_message` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The item type. Always `agent_message`. - `required` requires the model to call one or more of the allowed tools. + - `:agent_message` - - `:auto` + - `id: String` - - `:required` + The unique ID of this agent message item. - - `tools: Array[Hash[Symbol, untyped]]` + - `agent: Agent{ agent_name}` - A list of tool definitions that the model should be allowed to call. + The agent that produced this item. - For the Responses API, the list of tool definitions might look like: + - `agent_name: String` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The canonical name of the agent that produced this item. - - `type: :allowed_tools` + - `class MultiAgentCall` - Allowed tool configuration type. Always `allowed_tools`. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:allowed_tools` + The multi-agent action that was executed. - - `class BetaToolChoiceTypes` + - `:spawn_agent` - 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). + - `:interrupt_agent` - - `type: :file_search | :web_search_preview | :computer | 5 more` + - `:list_agents` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `:send_message` - Allowed values are: + - `:followup_task` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `:wait_agent` - - `:file_search` + - `arguments: String` - - `:web_search_preview` + The action arguments as a JSON string. - - `:computer` + - `call_id: String` - - `:computer_use_preview` + The unique ID linking this call to its output. - - `:computer_use` + - `type: :multi_agent_call` - - `:web_search_preview_2025_03_11` + The item type. Always `multi_agent_call`. - - `:image_generation` + - `:multi_agent_call` - - `:code_interpreter` + - `id: String` - - `class BetaToolChoiceFunction` + The unique ID of this multi-agent call. - Use this option to force the model to call a specific function. + - `agent: Agent{ agent_name}` - - `name: String` + The agent that produced this item. - The name of the function to call. + - `agent_name: String` - - `type: :function` + The canonical name of the agent that produced this item. - For function calling, the type is always `function`. + - `class MultiAgentCallOutput` - - `:function` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `class BetaToolChoiceMcp` + The multi-agent action that produced this result. - Use this option to force the model to call a specific tool on a remote MCP server. + - `:spawn_agent` - - `server_label: String` + - `:interrupt_agent` - The label of the MCP server to use. + - `:list_agents` - - `type: :mcp` + - `:send_message` - For MCP tools, the type is always `mcp`. + - `:followup_task` - - `:mcp` + - `:wait_agent` - - `name: String` + - `call_id: String` - The name of the tool to call on the server. + The unique ID of the multi-agent call. - - `class BetaToolChoiceCustom` + - `output: Array[Output{ text, type, annotations}]` - Use this option to force the model to call a specific custom tool. + Text output returned by the multi-agent action. - - `name: String` + - `text: String` - The name of the custom tool to call. + The text content. - - `type: :custom` + - `type: :output_text` - For custom tool calling, the type is always `custom`. + The content type. Always `output_text`. - - `:custom` + - `:output_text` - - `class BetaSpecificProgrammaticToolCallingParam` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `type: :programmatic_tool_calling` + Citations associated with the text content. - The tool to call. Always `programmatic_tool_calling`. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `:programmatic_tool_calling` + - `file_id: String` - - `class BetaToolChoiceApplyPatch` + The ID of the file. - Forces the model to call the apply_patch tool when executing a tool call. + - `filename: String` - - `type: :apply_patch` + The filename of the file cited. - The tool to call. Always `apply_patch`. + - `index: Integer` - - `:apply_patch` + The index of the file in the list of files. - - `class BetaToolChoiceShell` + - `type: :file_citation` - Forces the model to call the shell tool when a tool call is required. + The citation type. Always `file_citation`. - - `type: :shell` + - `:file_citation` - The tool to call. Always `shell`. + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - - `:shell` + - `end_index: Integer` - - `tools: Array[BetaTool]` + The index of the last character of the citation in the message. - 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. + - `start_index: Integer` - We support the following categories of tools: + The index of the first character of the citation in the message. - - **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. + - `title: String` - - `class BetaFunctionTool` + The title of the cited resource. - 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_citation` - - `class BetaFileSearchTool` + The citation type. Always `url_citation`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `:url_citation` - - `class BetaComputerTool` + - `url: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The URL of the cited resource. - - `class BetaComputerUsePreviewTool` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `container_id: String` - - `class BetaWebSearchTool` + The ID of the container. - 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). + - `end_index: Integer` - - `class Mcp` + The index of the last character of the citation in the message. - 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). + - `file_id: String` - - `class CodeInterpreter` + The ID of the container file. - A tool that runs Python code to help generate a response to a prompt. + - `filename: String` - - `class ProgrammaticToolCalling` + The filename of the container file cited. - - `class ImageGeneration` + - `start_index: Integer` - A tool that generates images using the GPT image models. + The index of the first character of the citation in the message. - - `class LocalShell` + - `type: :container_file_citation` - A tool that allows the model to execute shell commands in a local environment. + The citation type. Always `container_file_citation`. - - `class BetaFunctionShellTool` + - `:container_file_citation` - A tool that allows the model to execute shell commands. + - `type: :multi_agent_call_output` - - `class BetaCustomTool` + The item type. Always `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) + - `:multi_agent_call_output` - - `class BetaNamespaceTool` + - `id: String` - Groups function/custom tools under a shared namespace. + The unique ID of this multi-agent call output. - - `class BetaToolSearchTool` + - `agent: Agent{ agent_name}` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `class BetaWebSearchPreviewTool` + - `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. - - `class BetaApplyPatchTool` + - `class ToolSearchCall` - Allows the assistant to create, delete, or update files using unified diffs. + - `arguments: untyped` - - `top_p: Float` + The arguments supplied to the tool search call. - 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: :tool_search_call` - We generally recommend altering this or `temperature` but not both. + The item type. Always `tool_search_call`. - - `background: bool` + - `:tool_search_call` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `id: String` - - `completed_at: Float` + The unique ID of this tool search call. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `agent: Agent{ agent_name}` - - `conversation: Conversation{ 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. + - `call_id: String` - - `max_output_tokens: Integer` + The unique ID of the tool search call generated by the model. - 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). + - `execution: :server | :client` - - `max_tool_calls: Integer` + Whether tool search was executed by the server or by the client. - 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. + - `:server` - - `moderation: Moderation{ input, output}` + - `:client` - Moderation results for the response input and output, if moderated completions were requested. + - `status: :in_progress | :completed | :incomplete` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + The status of the tool search call. - Moderation for the response input. + - `:in_progress` - - `class ModerationResult` + - `:completed` - A moderation result produced for the response input or output. + - `:incomplete` - - `categories: Hash[Symbol, bool]` + - `class BetaResponseToolSearchOutputItemParam` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `tools: Array[BetaTool]` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The loaded tool definitions returned by the tool search output. - Which modalities of input are reflected by the score for each category. + - `class BetaFunctionTool` - - `:text` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `:image` + - `name: String` - - `category_scores: Hash[Symbol, Float]` + The name of the function to call. - A dictionary of moderation categories to scores. + - `parameters: Hash[Symbol, untyped]` - - `flagged: bool` + A JSON schema object describing the parameters of the function. - A boolean indicating whether the content was flagged by any category. + - `strict: bool` - - `model: String` + Whether strict parameter validation is enforced for this function tool. - The moderation model that produced this result. + - `type: :function` - - `type: :moderation_result` + The type of the function tool. Always `function`. - The object type, which was always `moderation_result` for successful moderation results. + - `:function` - - `:moderation_result` + - `allowed_callers: Array[:direct | :programmatic]` - - `class Error` + The tool invocation context(s). - An error produced while attempting moderation for the response input or output. + - `:direct` - - `code: String` + - `:programmatic` - The error code. + - `defer_loading: bool` - - `message: String` + Whether this function is deferred and loaded via tool search. - The error message. + - `description: String` - - `type: :error` + A description of the function. Used by the model to determine whether or not to call the function. - The object type, which was always `error` for moderation failures. + - `output_schema: Hash[Symbol, untyped]` - - `:error` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `class BetaFileSearchTool` - Moderation for the response 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). - - `class ModerationResult` + - `type: :file_search` - A moderation result produced for the response input or output. + The type of the file search tool. Always `file_search`. - - `categories: Hash[Symbol, bool]` + - `:file_search` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `vector_store_ids: Array[String]` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + The IDs of the vector stores to search. - Which modalities of input are reflected by the score for each category. + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - `:text` + A filter to apply. - - `:image` + - `class ComparisonFilter` - - `category_scores: Hash[Symbol, Float]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A dictionary of moderation categories to scores. + - `key: String` - - `flagged: bool` + The key to compare against the value. - A boolean indicating whether the content was flagged by any category. + - `type: :eq | :ne | :gt | 5 more` - - `model: String` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The moderation model that produced this result. + - `eq`: equals + - `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: :moderation_result` + - `:eq` - The object type, which was always `moderation_result` for successful moderation results. + - `:ne` - - `:moderation_result` + - `:gt` - - `class Error` + - `:gte` - An error produced while attempting moderation for the response input or output. + - `:lt` - - `code: String` + - `:lte` - The error code. + - `:in` - - `message: String` + - `:nin` - The error message. + - `value: String | Float | bool | Array[String | Float]` - - `type: :error` + The value to compare against the attribute key; supports string, number, or boolean types. - The object type, which was always `error` for moderation failures. + - `String = String` - - `:error` + - `Float = Float` - - `previous_response_id: String` + - `UnionMember2 = bool` - 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`. + - `UnionMember3 = Array[String | Float]` - - `prompt: BetaResponsePrompt` + - `String = String` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `Float = Float` - - `id: String` + - `class CompoundFilter` - The unique identifier of the prompt template to use. + Combine multiple filters using `and` or `or`. - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `String = String` + - `class ComparisonFilter` - - `class BetaResponseInputText` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A text input to the model. + - `key: String` - - `class BetaResponseInputImage` + The key to compare against the value. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: :eq | :ne | :gt | 5 more` - - `class BetaResponseInputFile` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A file input to the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `version: String` + - `:eq` - Optional version of the prompt template. + - `:ne` - - `prompt_cache_key: String` + - `:gt` - 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). + - `:gte` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `:lt` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `:lte` - - `mode: :implicit | :explicit` + - `:in` - Whether implicit prompt-cache breakpoints were enabled. + - `:nin` - - `:implicit` + - `value: String | Float | bool | Array[String | Float]` - - `:explicit` + The value to compare against the attribute key; supports string, number, or boolean types. - - `ttl: :"30m"` + - `String = String` - The minimum lifetime applied to each cache breakpoint. + - `Float = Float` - - `:"30m"` + - `UnionMember2 = bool` - - `prompt_cache_retention: :in_memory | :"24h"` + - `UnionMember3 = Array[String | Float]` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `String = 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. + - `Float = Float` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `UnionMember1 = untyped` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: :and | :or` - - `:in_memory` + Type of operation: `and` or `or`. - - `:"24h"` + - `:and` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `:or` - **gpt-5 and o-series models only** + - `max_num_results: Integer` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `context: :auto | :current_turn | :all_turns` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - 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. + Ranking options for search. - - `:auto` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `:current_turn` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `:all_turns` + - `embedding_weight: Float` - - `effort: :none | :minimal | :low | 4 more` + The weight of the embedding in the reciprocal ranking fusion. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `text_weight: Float` - - `:none` + The weight of the text in the reciprocal ranking fusion. - - `:minimal` + - `ranker: :auto | :"default-2024-11-15"` - - `:low` + The ranker to use for the file search. - - `:medium` + - `:auto` - - `:high` + - `:"default-2024-11-15"` - - `:xhigh` + - `score_threshold: Float` - - `:max` + 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. - - `generate_summary: :auto | :concise | :detailed` + - `class BetaComputerTool` - **Deprecated:** use `summary` instead. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - 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: :computer` - - `:auto` + The type of the computer tool. Always `computer`. - - `:concise` + - `:computer` - - `:detailed` + - `class BetaComputerUsePreviewTool` - - `mode: String | :standard | :pro` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Controls the reasoning execution mode for the request. + - `display_height: Integer` - When returned on a response, this is the effective execution mode. + The height of the computer display. - - `String = String` + - `display_width: Integer` - - `Mode = :standard | :pro` + The width of the computer display. - Controls the reasoning execution mode for the request. + - `environment: :windows | :mac | :linux | 2 more` - When returned on a response, this is the effective execution mode. + The type of computer environment to control. - - `:standard` + - `:windows` - - `:pro` + - `:mac` - - `summary: :auto | :concise | :detailed` + - `:linux` - 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`. + - `:ubuntu` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `:browser` - - `:auto` + - `type: :computer_use_preview` - - `:concise` + The type of the computer use tool. Always `computer_use_preview`. - - `:detailed` + - `:computer_use_preview` - - `safety_identifier: String` + - `class BetaWebSearchTool` - 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). + 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). - - `service_tier: :auto | :default | :flex | 2 more` + - `type: :web_search | :web_search_2025_08_26` - Specifies the processing type used for serving the request. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - 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'. + - `:web_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. + - `:web_search_2025_08_26` - - `:auto` + - `filters: Filters{ allowed_domains}` - - `:default` + Filters for the search. - - `:flex` + - `allowed_domains: Array[String]` - - `:scale` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `:priority` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `status: BetaResponseStatus` + - `search_context_size: :low | :medium | :high` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, 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. - - `:completed` + - `:low` - - `:failed` + - `:medium` - - `:in_progress` + - `:high` - - `:cancelled` + - `user_location: UserLocation{ city, country, region, 2 more}` - - `:queued` + The approximate location of the user. - - `:incomplete` + - `city: String` - - `text: BetaResponseTextConfig` + Free text input for the city of the user, e.g. `San Francisco`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `country: String` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `format_: BetaResponseFormatTextConfig` + - `region: String` - An object specifying the format that the model must output. + Free text input for the region of the user, e.g. `California`. - 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). + - `timezone: String` - The default format is `{ "type": "text" }` with no additional options. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - **Not recommended for gpt-4o and newer models:** + - `type: :approximate` - 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 location approximation. Always `approximate`. - - `class Text` + - `:approximate` - Default response format. Used to generate text responses. + - `class Mcp` - - `type: :text` + 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 type of response format being defined. Always `text`. + - `server_label: String` - - `:text` + A label for this MCP server, used to identify it in tool calls. - - `class BetaResponseFormatTextJSONSchemaConfig` + - `type: :mcp` - 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 MCP tool. Always `mcp`. - - `name: String` + - `:mcp` - 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. + - `allowed_callers: Array[:direct | :programmatic]` - - `schema: Hash[Symbol, untyped]` + The tool invocation context(s). - 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` + - `:programmatic` - The type of response format being defined. Always `json_schema`. + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - - `:json_schema` + List of allowed tool names or a filter object. - - `description: String` + - `McpAllowedTools = Array[String]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A string array of allowed tool names - - `strict: bool` + - `class McpToolFilter` - 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). + A filter object to specify which tools are allowed. - - `class JSONObject` + - `read_only: bool` - 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. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: :json_object` + - `tool_names: Array[String]` - The type of response format being defined. Always `json_object`. + List of allowed tool names. - - `:json_object` + - `authorization: String` - - `verbosity: :low | :medium | :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. - 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`. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `:low` + 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). - - `:medium` + 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` - - `top_logprobs: Integer` + - `:connector_dropbox` - 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. + - `:connector_gmail` - - `truncation: :auto | :disabled` + - `:connector_googlecalendar` - The truncation strategy to use for the model response. + - `:connector_googledrive` - - `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. + - `:connector_microsoftteams` - - `:auto` + - `:connector_outlookcalendar` - - `:disabled` + - `:connector_outlookemail` - - `usage: BetaResponseUsage` + - `:connector_sharepoint` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `defer_loading: bool` - - `input_tokens: Integer` + Whether this MCP tool is deferred and discovered via tool search. - The number of input tokens. + - `headers: Hash[Symbol, String]` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - A detailed breakdown of the input tokens. + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `cache_write_tokens: Integer` + Specify which of the MCP server's tools require approval. - The number of input tokens that were written to the cache. + - `class McpToolApprovalFilter` - - `cached_tokens: Integer` + 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 were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `always: Always{ read_only, tool_names}` - - `output_tokens: Integer` + A filter object to specify which tools are allowed. - The number of output tokens. + - `read_only: bool` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A detailed breakdown of the output tokens. + - `tool_names: Array[String]` - - `reasoning_tokens: Integer` + List of allowed tool names. - The number of reasoning tokens. + - `never: Never{ read_only, tool_names}` - - `total_tokens: Integer` + A filter object to specify which tools are allowed. - The total number of tokens used. + - `read_only: bool` - - `user: 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. - 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). + - `tool_names: Array[String]` - - `sequence_number: Integer` + List of allowed tool names. - The sequence number for this event. + - `McpToolApprovalSetting = :always | :never` - - `type: :"response.queued"` + 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.queued'. + - `:always` - - `:"response.queued"` + - `:never` - - `agent: Agent{ agent_name}` + - `server_description: 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: String` - The canonical name of the agent that produced this item. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. -### Beta Response Reasoning Item + - `tunnel_id: String` -- `class BetaResponseReasoningItem` + 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 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). + - `class CodeInterpreter` - - `id: String` + A tool that runs Python code to help generate a response to a prompt. - The unique identifier of the reasoning content. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `summary: Array[Summary{ 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. - Reasoning summary content. + - `String = String` - - `text: String` + The container ID. - A summary of the reasoning output from the model so far. + - `class CodeInterpreterToolAuto` - - `type: :summary_text` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The type of the object. Always `summary_text`. + - `type: :auto` - - `:summary_text` + Always `auto`. - - `type: :reasoning` + - `:auto` - The type of the object. Always `reasoning`. + - `file_ids: Array[String]` - - `:reasoning` + An optional list of uploaded files to make available to your code. - - `agent: Agent{ agent_name}` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"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"` - - `content: Array[Content{ text, type}]` + - `:"16g"` - Reasoning text content. + - `:"64g"` - - `text: String` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The reasoning text from the model. + Network access policy for the container. - - `type: :reasoning_text` + - `class BetaContainerNetworkPolicyDisabled` - The type of the reasoning text. Always `reasoning_text`. + - `type: :disabled` - - `:reasoning_text` + Disable outbound network access. Always `disabled`. - - `encrypted_content: String` + - `:disabled` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `class BetaContainerNetworkPolicyAllowlist` - - `status: :in_progress | :completed | :incomplete` + - `allowed_domains: Array[String]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A list of allowed domains when type is `allowlist`. - - `:in_progress` + - `type: :allowlist` - - `:completed` + Allow outbound network access only to specified domains. Always `allowlist`. - - `:incomplete` + - `:allowlist` -### Beta Response Reasoning Summary Part Added Event + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` -- `class BetaResponseReasoningSummaryPartAddedEvent` + Optional domain-scoped secrets for allowlisted domains. - Emitted when a new reasoning summary part is added. + - `domain: String` - - `item_id: String` + The domain associated with the secret. - The ID of the item this summary part is associated with. + - `name: String` - - `output_index: Integer` + The name of the secret to inject for the domain. - The index of the output item this summary part is associated with. + - `value: String` - - `part: Part{ text, type}` + The secret value to inject for the domain. - The summary part that was added. + - `type: :code_interpreter` - - `text: String` + The type of the code interpreter tool. Always `code_interpreter`. - The text of the summary part. + - `:code_interpreter` - - `type: :summary_text` + - `allowed_callers: Array[:direct | :programmatic]` - The type of the summary part. Always `summary_text`. + The tool invocation context(s). - - `:summary_text` + - `:direct` - - `sequence_number: Integer` + - `:programmatic` - The sequence number of this event. + - `class ProgrammaticToolCalling` - - `summary_index: Integer` + - `type: :programmatic_tool_calling` - The index of the summary part within the reasoning summary. + The type of the tool. Always `programmatic_tool_calling`. - - `type: :"response.reasoning_summary_part.added"` + - `:programmatic_tool_calling` - The type of the event. Always `response.reasoning_summary_part.added`. + - `class ImageGeneration` - - `:"response.reasoning_summary_part.added"` + A tool that generates images using the GPT image models. - - `agent: Agent{ agent_name}` + - `type: :image_generation` - The agent that owns this multi-agent streaming event. + The type of the image generation tool. Always `image_generation`. - - `agent_name: String` + - `:image_generation` - The canonical name of the agent that produced this item. + - `action: :generate | :edit | :auto` -### Beta Response Reasoning Summary Part Done Event + Whether to generate a new image or edit an existing image. Default: `auto`. -- `class BetaResponseReasoningSummaryPartDoneEvent` + - `:generate` - Emitted when a reasoning summary part is completed. + - `:edit` - - `item_id: String` + - `:auto` - The ID of the item this summary part is associated with. + - `background: :transparent | :opaque | :auto` - - `output_index: Integer` + 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 index of the output item this summary part is associated with. + `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. - - `part: Part{ text, type}` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The completed summary part. + - `:transparent` - - `text: String` + - `:opaque` - The text of the summary part. + - `:auto` - - `type: :summary_text` + - `input_fidelity: :high | :low` - The type of the summary part. Always `summary_text`. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `:summary_text` + - `:high` - - `sequence_number: Integer` + - `:low` - The sequence number of this event. + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `summary_index: Integer` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The index of the summary part within the reasoning summary. + - `file_id: String` - - `type: :"response.reasoning_summary_part.done"` + File ID for the mask image. - The type of the event. Always `response.reasoning_summary_part.done`. + - `image_url: String` - - `:"response.reasoning_summary_part.done"` + Base64-encoded mask image. - - `agent: Agent{ agent_name}` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - The agent that owns this multi-agent streaming event. + The image generation model to use. Default: `gpt-image-1`. - - `agent_name: String` + - `String = String` - The canonical name of the agent that produced this item. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `status: :incomplete` + The image generation model to use. Default: `gpt-image-1`. - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `:"gpt-image-1"` - - `:incomplete` + - `:"gpt-image-1-mini"` -### Beta Response Reasoning Summary Text Delta Event + - `:"gpt-image-2"` -- `class BetaResponseReasoningSummaryTextDeltaEvent` + - `:"gpt-image-2-2026-04-21"` - Emitted when a delta is added to a reasoning summary text. + - `:"gpt-image-1.5"` - - `delta: String` + - `:"chatgpt-image-latest"` - The text delta that was added to the summary. + - `moderation: :auto | :low` - - `item_id: String` + Moderation level for the generated image. Default: `auto`. - The ID of the item this summary text delta is associated with. + - `:auto` - - `output_index: Integer` + - `:low` - The index of the output item this summary text delta is associated with. + - `output_compression: Integer` - - `sequence_number: Integer` + Compression level for the output image. Default: 100. - The sequence number of this event. + - `output_format: :png | :webp | :jpeg` - - `summary_index: Integer` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The index of the summary part within the reasoning summary. + - `:png` - - `type: :"response.reasoning_summary_text.delta"` + - `:webp` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `:jpeg` - - `:"response.reasoning_summary_text.delta"` + - `partial_images: Integer` - - `agent: Agent{ agent_name}` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The agent that owns this multi-agent streaming event. + - `quality: :low | :medium | :high | :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` -### Beta Response Reasoning Summary Text Done Event + - `:medium` -- `class BetaResponseReasoningSummaryTextDoneEvent` + - `:high` - Emitted when a reasoning summary text is completed. + - `:auto` - - `item_id: String` + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - The ID of the item this summary text is associated with. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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_index: Integer` + - `String = String` - The index of the output item this summary text is associated with. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `sequence_number: Integer` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The sequence number of this event. + - `:"1024x1024"` - - `summary_index: Integer` + - `:"1024x1536"` - The index of the summary part within the reasoning summary. + - `:"1536x1024"` - - `text: String` + - `:auto` - The full text of the completed reasoning summary. + - `class LocalShell` - - `type: :"response.reasoning_summary_text.done"` + A tool that allows the model to execute shell commands in a local environment. - The type of the event. Always `response.reasoning_summary_text.done`. + - `type: :local_shell` - - `:"response.reasoning_summary_text.done"` + The type of the local shell tool. Always `local_shell`. - - `agent: Agent{ agent_name}` + - `:local_shell` - The agent that owns this multi-agent streaming event. + - `class BetaFunctionShellTool` - - `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` -### Beta Response Reasoning Text Delta Event + The type of the shell tool. Always `shell`. -- `class BetaResponseReasoningTextDeltaEvent` + - `:shell` - Emitted when a delta is added to a reasoning text. + - `allowed_callers: Array[:direct | :programmatic]` - - `content_index: Integer` + 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. + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `item_id: String` + - `class BetaContainerAuto` - The ID of the item this reasoning text delta is associated with. + - `type: :container_auto` - - `output_index: Integer` + Automatically creates a container for this request - The index of the output item this reasoning text delta is associated with. + - `:container_auto` - - `sequence_number: Integer` + - `file_ids: Array[String]` - The sequence number of this event. + An optional list of uploaded files to make available to your code. - - `type: :"response.reasoning_text.delta"` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The type of the event. Always `response.reasoning_text.delta`. + The memory limit for the container. - - `:"response.reasoning_text.delta"` + - `:"1g"` - - `agent: Agent{ agent_name}` + - `:"4g"` - The agent that owns this multi-agent streaming event. + - `:"16g"` - - `agent_name: String` + - `:"64g"` - The canonical name of the agent that produced this item. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` -### Beta Response Reasoning Text Done Event + Network access policy for the container. -- `class BetaResponseReasoningTextDoneEvent` + - `class BetaContainerNetworkPolicyDisabled` - Emitted when a reasoning text is completed. + - `class BetaContainerNetworkPolicyAllowlist` - - `content_index: Integer` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - The index of the reasoning content part. + An optional list of skills referenced by id or inline data. - - `item_id: String` + - `class BetaSkillReference` - The ID of the item this reasoning text is associated with. + - `skill_id: String` - - `output_index: Integer` + The ID of the referenced skill. - The index of the output item this reasoning text is associated with. + - `type: :skill_reference` - - `sequence_number: Integer` + References a skill created with the /v1/skills endpoint. - The sequence number of this event. + - `:skill_reference` - - `text: String` + - `version: String` - The full text of the completed reasoning content. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: :"response.reasoning_text.done"` + - `class BetaInlineSkill` - The type of the event. Always `response.reasoning_text.done`. + - `description: String` - - `:"response.reasoning_text.done"` + The description of the skill. - - `agent: Agent{ agent_name}` + - `name: String` - The agent that owns this multi-agent streaming event. + The name of the skill. - - `agent_name: String` + - `source: BetaInlineSkillSource` - The canonical name of the agent that produced this item. + Inline skill payload -### Beta Response Refusal Delta Event + - `data: String` -- `class BetaResponseRefusalDeltaEvent` + Base64-encoded skill zip bundle. - Emitted when there is a partial refusal text. + - `media_type: :"application/zip"` - - `content_index: Integer` + The media type of the inline skill payload. Must be `application/zip`. - The index of the content part that the refusal text is added to. + - `:"application/zip"` - - `delta: String` + - `type: :base64` - The refusal text that is added. + The type of the inline skill source. Must be `base64`. - - `item_id: String` + - `:base64` - The ID of the output item that the refusal text is added to. + - `type: :inline` - - `output_index: Integer` + Defines an inline skill for this request. - The index of the output item that the refusal text is added to. + - `:inline` - - `sequence_number: Integer` + - `class BetaLocalEnvironment` - The sequence number of this event. + - `type: :local` - - `type: :"response.refusal.delta"` + Use a local computer environment. - The type of the event. Always `response.refusal.delta`. + - `:local` - - `:"response.refusal.delta"` + - `skills: Array[BetaLocalSkill]` - - `agent: Agent{ agent_name}` + An optional list of skills. - The agent that owns this multi-agent streaming event. + - `description: String` - - `agent_name: String` + The description of the skill. - The canonical name of the agent that produced this item. + - `name: String` -### Beta Response Refusal Done Event + The name of the skill. -- `class BetaResponseRefusalDoneEvent` + - `path: String` - Emitted when refusal text is finalized. + The path to the directory containing the skill. - - `content_index: Integer` + - `class BetaContainerReference` - The index of the content part that the refusal text is finalized. + - `container_id: String` - - `item_id: String` + The ID of the referenced container. - The ID of the output item that the refusal text is finalized. + - `type: :container_reference` - - `output_index: Integer` + References a container created with the /v1/containers endpoint - The index of the output item that the refusal text is finalized. + - `:container_reference` - - `refusal: String` + - `class BetaCustomTool` - The refusal text that is finalized. + 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: Integer` + - `name: String` - The sequence number of this event. + The name of the custom tool, used to identify it in tool calls. - - `type: :"response.refusal.done"` + - `type: :custom` - The type of the event. Always `response.refusal.done`. + The type of the custom tool. Always `custom`. - - `:"response.refusal.done"` + - `:custom` - - `agent: Agent{ agent_name}` + - `allowed_callers: Array[:direct | :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 Status + - `defer_loading: bool` -- `BetaResponseStatus = :completed | :failed | :in_progress | 3 more` + Whether this tool should be deferred and discovered via tool search. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `description: String` - - `:completed` + Optional description of the custom tool, used to provide more context. - - `:failed` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `:in_progress` + The input format for the custom tool. Default is unconstrained text. - - `:cancelled` + - `class Text` - - `:queued` + Unconstrained free-form text. - - `:incomplete` + - `type: :text` -### Beta Response Stream Event + Unconstrained text format. Always `text`. -- `BetaResponseStreamEvent = BetaResponseAudioDeltaEvent | BetaResponseAudioDoneEvent | BetaResponseAudioTranscriptDeltaEvent | 50 more` + - `:text` - Emitted when there is a partial audio response. + - `class Grammar` - - `class BetaResponseAudioDeltaEvent` + A grammar defined by the user. - Emitted when there is a partial audio response. + - `definition: String` - - `delta: String` + The grammar definition. - A chunk of Base64 encoded response audio bytes. + - `syntax: :lark | :regex` - - `sequence_number: Integer` + The syntax of the grammar definition. One of `lark` or `regex`. - A sequence number for this chunk of the stream response. + - `:lark` - - `type: :"response.audio.delta"` + - `:regex` - The type of the event. Always `response.audio.delta`. + - `type: :grammar` - - `:"response.audio.delta"` + Grammar format. Always `grammar`. - - `agent: Agent{ agent_name}` + - `:grammar` - The agent that owns this multi-agent streaming event. + - `class BetaNamespaceTool` - - `agent_name: String` + Groups function/custom tools under a shared namespace. - The canonical name of the agent that produced this item. + - `description: String` - - `class BetaResponseAudioDoneEvent` + A description of the namespace shown to the model. - Emitted when the audio response is complete. + - `name: String` - - `sequence_number: Integer` + The namespace name used in tool calls (for example, `crm`). - The sequence number of the delta. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `type: :"response.audio.done"` + The function/custom tools available inside this namespace. - The type of the event. Always `response.audio.done`. + - `class Function` - - `:"response.audio.done"` + - `name: String` - - `agent: Agent{ agent_name}` + - `type: :function` - The agent that owns this multi-agent streaming event. + - `:function` - - `agent_name: String` + - `allowed_callers: Array[:direct | :programmatic]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `class BetaResponseAudioTranscriptDeltaEvent` + - `:direct` - Emitted when there is a partial transcript of audio. + - `:programmatic` - - `delta: String` + - `defer_loading: bool` - The partial transcript of the audio response. + Whether this function should be deferred and discovered via tool search. - - `sequence_number: Integer` + - `description: String` - The sequence number of this event. + - `output_schema: Hash[Symbol, untyped]` - - `type: :"response.audio.transcript.delta"` + 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 event. Always `response.audio.transcript.delta`. + - `parameters: untyped` - - `:"response.audio.transcript.delta"` + - `strict: bool` - - `agent: Agent{ 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 owns this multi-agent streaming event. + - `class BetaCustomTool` - - `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. + - `type: :namespace` - - `class BetaResponseAudioTranscriptDoneEvent` + The type of the tool. Always `namespace`. - Emitted when the full audio transcript is completed. + - `:namespace` - - `sequence_number: Integer` + - `class BetaToolSearchTool` - The sequence number of this event. + Hosted or BYOT tool search configuration for deferred tools. - - `type: :"response.audio.transcript.done"` + - `type: :tool_search` - The type of the event. Always `response.audio.transcript.done`. + The type of the tool. Always `tool_search`. - - `:"response.audio.transcript.done"` + - `:tool_search` - - `agent: Agent{ agent_name}` + - `description: 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: :server | :client` - The canonical name of the agent that produced this item. + Whether tool search is executed by the server or by the client. - - `class BetaResponseCodeInterpreterCallCodeDeltaEvent` + - `:server` - Emitted when a partial code snippet is streamed by the code interpreter. + - `:client` - - `delta: String` + - `parameters: untyped` - The partial code snippet being streamed by the code interpreter. + Parameter schema for a client-executed tool search tool. - - `item_id: String` + - `class BetaWebSearchPreviewTool` - The unique identifier of the code interpreter tool call 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). - - `output_index: Integer` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - The index of the output item in the response for which the code is being streamed. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `sequence_number: Integer` + - `:web_search_preview` - The sequence number of this event, used to order streaming events. + - `:web_search_preview_2025_03_11` - - `type: :"response.code_interpreter_call_code.delta"` + - `search_content_types: Array[:text | :image]` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `:text` - - `:"response.code_interpreter_call_code.delta"` + - `:image` - - `agent: Agent{ agent_name}` + - `search_context_size: :low | :medium | :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` - - `class BetaResponseCodeInterpreterCallCodeDoneEvent` + - `:high` - Emitted when the code snippet is finalized by the code interpreter. + - `user_location: UserLocation{ type, city, country, 2 more}` - - `code: String` + The user's location. - The final code snippet output by the code interpreter. + - `type: :approximate` - - `item_id: String` + The type of location approximation. Always `approximate`. - The unique identifier of the code interpreter tool call item. + - `:approximate` - - `output_index: Integer` + - `city: String` - The index of the output item in the response for which the code is finalized. + Free text input for the city of the user, e.g. `San Francisco`. - - `sequence_number: Integer` + - `country: String` - The sequence number of this event, used to order streaming events. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: :"response.code_interpreter_call_code.done"` + - `region: String` - The type of the event. Always `response.code_interpreter_call_code.done`. + Free text input for the region of the user, e.g. `California`. - - `:"response.code_interpreter_call_code.done"` + - `timezone: String` - - `agent: Agent{ 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. + - `class BetaApplyPatchTool` - - `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` - - `class BetaResponseCodeInterpreterCallCompletedEvent` + The type of the tool. Always `apply_patch`. - Emitted when the code interpreter call is completed. + - `:apply_patch` - - `item_id: String` + - `allowed_callers: Array[:direct | :programmatic]` - The unique identifier of the code interpreter tool call item. + The tool invocation context(s). - - `output_index: Integer` + - `:direct` - The index of the output item in the response for which the code interpreter call is completed. + - `:programmatic` - - `sequence_number: Integer` + - `type: :tool_search_output` - The sequence number of this event, used to order streaming events. + The item type. Always `tool_search_output`. - - `type: :"response.code_interpreter_call.completed"` + - `:tool_search_output` - The type of the event. Always `response.code_interpreter_call.completed`. + - `id: String` - - `:"response.code_interpreter_call.completed"` + The unique ID of this tool search output. - `agent: Agent{ 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. - - `class BetaResponseCodeInterpreterCallInProgressEvent` - - Emitted when a code interpreter call is in progress. - - - `item_id: String` - - The unique identifier of the code interpreter tool call item. - - - `output_index: Integer` - - The index of the output item in the response for which the code interpreter call is in progress. + - `call_id: String` - - `sequence_number: Integer` + The unique ID of the tool search call generated by the model. - The sequence number of this event, used to order streaming events. + - `execution: :server | :client` - - `type: :"response.code_interpreter_call.in_progress"` + Whether tool search was executed by the server or by the client. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `:server` - - `:"response.code_interpreter_call.in_progress"` + - `:client` - - `agent: Agent{ agent_name}` + - `status: :in_progress | :completed | :incomplete` - The agent that owns this multi-agent streaming event. + The status of the tool search output. - - `agent_name: String` + - `:in_progress` - The canonical name of the agent that produced this item. + - `:completed` - - `class BetaResponseCodeInterpreterCallInterpretingEvent` + - `:incomplete` - Emitted when the code interpreter is actively interpreting the code snippet. + - `class AdditionalTools` - - `item_id: String` + - `role: :developer` - The unique identifier of the code interpreter tool call item. + The role that provided the additional tools. Only `developer` is supported. - - `output_index: Integer` + - `:developer` - The index of the output item in the response for which the code interpreter is interpreting code. + - `tools: Array[BetaTool]` - - `sequence_number: Integer` + A list of additional tools made available at this item. - The sequence number of this event, used to order streaming events. + - `class BetaFunctionTool` - - `type: :"response.code_interpreter_call.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). - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `class BetaFileSearchTool` - - `:"response.code_interpreter_call.interpreting"` + 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: Agent{ agent_name}` + - `class BetaComputerTool` - The agent that owns this multi-agent streaming event. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent_name: String` + - `class BetaComputerUsePreviewTool` - 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). - - `class BetaResponseCompletedEvent` + - `class BetaWebSearchTool` - Emitted when the model response is complete. + 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). - - `response: BetaResponse` + - `class Mcp` - Properties of the completed response. + 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` + - `class CodeInterpreter` - Unique identifier for this Response. + A tool that runs Python code to help generate a response to a prompt. - - `created_at: Float` + - `class ProgrammaticToolCalling` - Unix timestamp (in seconds) of when this Response was created. + - `class ImageGeneration` - - `error: BetaResponseError` + A tool that generates images using the GPT image models. - An error object returned when the model fails to generate a Response. + - `class LocalShell` - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + A tool that allows the model to execute shell commands in a local environment. - The error code for the response. + - `class BetaFunctionShellTool` - - `:server_error` + A tool that allows the model to execute shell commands. - - `:rate_limit_exceeded` + - `class BetaCustomTool` - - `:invalid_prompt` + 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) - - `:bio_policy` + - `class BetaNamespaceTool` - - `:vector_store_timeout` + Groups function/custom tools under a shared namespace. - - `:invalid_image` + - `class BetaToolSearchTool` - - `:invalid_image_format` + Hosted or BYOT tool search configuration for deferred tools. - - `:invalid_base64_image` + - `class BetaWebSearchPreviewTool` - - `:invalid_image_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). - - `:image_too_large` + - `class BetaApplyPatchTool` - - `:image_too_small` + Allows the assistant to create, delete, or update files using unified diffs. - - `:image_parse_error` + - `type: :additional_tools` - - `:image_content_policy_violation` + The item type. Always `additional_tools`. - - `:invalid_image_mode` + - `:additional_tools` - - `:image_file_too_large` + - `id: String` - - `:unsupported_image_media_type` + The unique ID of this additional tools item. - - `:empty_image_file` + - `agent: Agent{ agent_name}` - - `:failed_to_download_image` + The agent that produced this item. - - `:image_file_not_found` + - `agent_name: String` - - `message: String` + The canonical name of the agent that produced this item. - A human-readable description of the error. + - `class BetaResponseReasoningItem` - - `incomplete_details: IncompleteDetails{ reason}` + 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). - Details about why the response is incomplete. + - `id: String` - - `reason: :max_output_tokens | :content_filter` + The unique identifier of the reasoning content. - The reason why the response is incomplete. + - `summary: Array[Summary{ text, type}]` - - `:max_output_tokens` + Reasoning summary content. - - `:content_filter` + - `text: String` - - `instructions: String | Array[BetaResponseInputItem]` + A summary of the reasoning output from the model so far. - A system (or developer) message inserted into the model's context. + - `type: :summary_text` - 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 object. Always `summary_text`. - - `String = String` + - `:summary_text` - A text input to the model, equivalent to a text input with the - `developer` role. + - `type: :reasoning` - - `InputItemList = Array[BetaResponseInputItem]` + The type of the object. Always `reasoning`. - A list of one or many input items to the model, containing - different content types. + - `:reasoning` - - `class BetaEasyInputMessage` + - `agent: Agent{ agent_name}` - 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 agent that produced this item. - - `content: String | BetaResponseInputMessageContentList` + - `agent_name: String` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The canonical name of the agent that produced this item. - - `String = String` + - `content: Array[Content{ text, type}]` - A text input to the model. + Reasoning text content. - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `text: String` - A list of one or many input items to the model, containing different content - types. + The reasoning text from the model. - - `class BetaResponseInputText` + - `type: :reasoning_text` - A text input to the model. + The type of the reasoning text. Always `reasoning_text`. - - `text: String` + - `:reasoning_text` - The text input to the model. + - `encrypted_content: String` - - `type: :input_text` + 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 input item. Always `input_text`. + - `status: :in_progress | :completed | :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: PromptCacheBreakpoint{ 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`. + - `class BetaResponseCompactionItemParam` - - `:explicit` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `class BetaResponseInputImage` + - `encrypted_content: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The encrypted content of the compaction summary. - - `detail: :low | :high | :auto | :original` + - `type: :compaction` - 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 item. Always `compaction`. - - `:low` + - `:compaction` - - `:high` + - `id: String` - - `:auto` + The ID of the compaction item. - - `:original` + - `agent: Agent{ 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: String` + - `class ImageGenerationCall` - The ID of the file to be sent to the model. + An image generation request made by the model. - - `image_url: String` + - `id: String` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The unique ID of the image generation call. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `result: 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 generated image encoded in base64. - - `mode: :explicit` + - `status: :in_progress | :completed | :generating | :failed` - The breakpoint mode. Always `explicit`. + The status of the image generation call. - - `:explicit` + - `:in_progress` - - `class BetaResponseInputFile` + - `:completed` - A file input to the model. + - `:generating` - - `type: :input_file` + - `:failed` - The type of the input item. Always `input_file`. + - `type: :image_generation_call` - - `:input_file` + The type of the image generation call. Always `image_generation_call`. - - `detail: :auto | :low | :high` + - `:image_generation_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`. + - `agent: Agent{ 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_data: String` + - `class BetaResponseCodeInterpreterToolCall` - The content of the file to be sent to the model. + A tool call to run code. - - `file_id: String` + - `id: String` - The ID of the file to be sent to the model. + The unique ID of the code interpreter tool call. - - `file_url: String` + - `code: String` - The URL of the file to be sent to the model. + The code to run, or null if not available. - - `filename: String` + - `container_id: String` - The name of the file to be sent to the model. + The ID of the container used to run the code. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `mode: :explicit` + - `class Logs` - The breakpoint mode. Always `explicit`. + The logs output from the code interpreter. - - `:explicit` + - `logs: String` - - `role: :user | :assistant | :system | :developer` + The logs output from the code interpreter. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `type: :logs` - - `:user` + The type of the output. Always `logs`. - - `:assistant` + - `:logs` - - `:system` + - `class Image` - - `:developer` + The image output from the code interpreter. - - `phase: :commentary` + - `type: :image` - 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 output. Always `image`. - - `:commentary` + - `:image` - - `type: :message` + - `url: String` - The type of the message input. Always `message`. + The URL of the image output from the code interpreter. - - `:message` + - `status: :in_progress | :completed | :incomplete | 2 more` - - `class Message` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `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. + - `:in_progress` - - `content: BetaResponseInputMessageContentList` + - `:completed` - A list of one or many input items to the model, containing different content - types. + - `:incomplete` - - `role: :user | :system | :developer` + - `:interpreting` - The role of the message input. One of `user`, `system`, or `developer`. + - `:failed` - - `:user` + - `type: :code_interpreter_call` - - `:system` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `:developer` + - `:code_interpreter_call` - `agent: Agent{ agent_name}` @@ -124571,189 +137306,185 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :incomplete` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class LocalShellCall` - - `:in_progress` + A tool call to run a command on the local shell. - - `:completed` + - `id: String` - - `:incomplete` + The unique ID of the local shell call. - - `type: :message` + - `action: Action{ command, env, type, 3 more}` - The type of the message input. Always set to `message`. + Execute a shell command on the server. - - `:message` + - `command: Array[String]` - - `class BetaResponseOutputMessage` + The command to run. - An output message from the model. + - `env: Hash[Symbol, String]` - - `id: String` + Environment variables to set for the command. - The unique ID of the output message. + - `type: :exec` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + The type of the local shell action. Always `exec`. - The content of the output message. + - `:exec` - - `class BetaResponseOutputText` + - `timeout_ms: Integer` - A text output from the model. + Optional timeout in milliseconds for the command. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `user: String` - The annotations of the text output. + Optional user to run the command as. - - `class FileCitation` + - `working_directory: String` - A citation to a file. + Optional working directory to run the command in. - - `file_id: String` + - `call_id: String` - The ID of the file. + The unique ID of the local shell tool call generated by the model. - - `filename: String` + - `status: :in_progress | :completed | :incomplete` - The filename of the file cited. + The status of the local shell call. - - `index: Integer` + - `:in_progress` - The index of the file in the list of files. + - `:completed` - - `type: :file_citation` + - `:incomplete` - The type of the file citation. Always `file_citation`. + - `type: :local_shell_call` - - `:file_citation` + The type of the local shell call. Always `local_shell_call`. - - `class URLCitation` + - `:local_shell_call` - A citation for a web resource used to generate a model response. + - `agent: Agent{ agent_name}` - - `end_index: Integer` + The agent that produced this item. - The index of the last character of the URL citation in the message. + - `agent_name: String` - - `start_index: Integer` + The canonical name of the agent that produced this item. - The index of the first character of the URL citation in the message. + - `class LocalShellCallOutput` - - `title: String` + The output of a local shell tool call. - The title of the web resource. + - `id: String` - - `type: :url_citation` + The unique ID of the local shell tool call generated by the model. - The type of the URL citation. Always `url_citation`. + - `output: String` - - `:url_citation` + A JSON string of the output of the local shell tool call. - - `url: String` + - `type: :local_shell_call_output` - The URL of the web resource. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `class ContainerFileCitation` + - `:local_shell_call_output` - A citation for a container file used to generate a model response. + - `agent: Agent{ agent_name}` - - `container_id: String` + The agent that produced this item. - The ID of the container file. + - `agent_name: String` - - `end_index: Integer` + The canonical name of the agent that produced this item. - The index of the last character of the container file citation in the message. + - `status: :in_progress | :completed | :incomplete` - - `file_id: String` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The ID of the file. + - `:in_progress` - - `filename: String` + - `:completed` - The filename of the container file cited. + - `:incomplete` - - `start_index: Integer` + - `class ShellCall` - The index of the first character of the container file citation in the message. + A tool representing a request to execute one or more shell commands. - - `type: :container_file_citation` + - `action: Action{ commands, max_output_length, timeout_ms}` - The type of the container file citation. Always `container_file_citation`. + The shell commands and limits that describe how to run the tool call. - - `:container_file_citation` + - `commands: Array[String]` - - `class FilePath` + Ordered shell commands for the execution environment to run. - A path to a file. + - `max_output_length: Integer` - - `file_id: String` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The ID of the file. + - `timeout_ms: Integer` - - `index: Integer` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The index of the file in the list of files. + - `call_id: String` - - `type: :file_path` + The unique ID of the shell tool call generated by the model. - The type of the file path. Always `file_path`. + - `type: :shell_call` - - `:file_path` + The type of the item. Always `shell_call`. - - `text: String` + - `:shell_call` - The text output from the model. + - `id: String` - - `type: :output_text` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of the output text. Always `output_text`. + - `agent: Agent{ agent_name}` - - `:output_text` + The agent that produced this item. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `agent_name: String` - - `token: String` + The canonical name of the agent that produced this item. - - `bytes: Array[Integer]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `logprob: Float` + The execution context that produced this tool call. - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `class Direct` - - `token: String` + - `type: :direct` - - `bytes: Array[Integer]` + The caller type. Always `direct`. - - `logprob: Float` + - `:direct` - - `class BetaResponseOutputRefusal` + - `class Program` - 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` + - `environment: BetaLocalEnvironment | BetaContainerReference` - - `role: :assistant` + The environment to execute the shell commands in. - The role of the output message. Always `assistant`. + - `class BetaLocalEnvironment` - - `:assistant` + - `class BetaContainerReference` - `status: :in_progress | :completed | :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 shell call. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` @@ -124761,61 +137492,63 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :message` + - `class ShellCallOutput` - The type of the output message. Always `message`. + The streamed output items emitted by a shell tool call. - - `:message` + - `call_id: String` - - `agent: Agent{ agent_name}` + The unique ID of the shell tool call generated by the model. - The agent that produced this item. + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - - `agent_name: String` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The canonical name of the agent that produced this item. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `phase: :commentary` + The exit or timeout outcome associated with this 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. + - `class Timeout` - - `:commentary` + Indicates that the shell call exceeded its configured time limit. - - `class BetaResponseFileSearchToolCall` + - `type: :timeout` - 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 outcome type. Always `timeout`. - - `id: String` + - `:timeout` - The unique ID of the file search tool call. + - `class Exit` - - `queries: Array[String]` + Indicates that the shell commands finished and returned an exit code. - The queries used to search for files. + - `exit_code: Integer` - - `status: :in_progress | :searching | :completed | 2 more` + The exit code returned by the shell process. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `type: :exit` - - `:in_progress` + The outcome type. Always `exit`. - - `:searching` + - `:exit` - - `:completed` + - `stderr: String` - - `:incomplete` + Captured stderr output for the shell call. - - `:failed` + - `stdout: String` - - `type: :file_search_call` + Captured stdout output for the shell call. - The type of the file search tool call. Always `file_search_call`. + - `type: :shell_call_output` - - `:file_search_call` + The type of the item. Always `shell_call_output`. + + - `:shell_call_output` + + - `id: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` @@ -124825,321 +137558,293 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - The results of the file search tool call. - - - `attributes: Hash[Symbol, String | Float | bool]` - - Set of 16 key-value pairs that can be attached to an object. 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 = String` - - - `Float = Float` - - - `UnionMember2 = bool` - - - `file_id: String` - - The unique ID of the file. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `filename: String` + The execution context that produced this tool call. - The name of the file. + - `class Direct` - - `score: Float` + - `type: :direct` - The relevance score of the file - a value between 0 and 1. + The caller type. Always `direct`. - - `text: String` + - `:direct` - The text that was retrieved from the file. + - `class Program` - - `class BetaResponseComputerToolCall` + - `caller_id: 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. + The call ID of the program item that produced this tool call. - - `id: String` + - `type: :program` - The unique ID of the computer call. + The caller type. Always `program`. - - `call_id: String` + - `:program` - An identifier used when responding to the tool call with output. + - `max_output_length: Integer` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The pending safety checks for the computer call. + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the shell call output. - The ID of the pending safety check. + - `:in_progress` - - `code: String` + - `:completed` - The type of the pending safety check. + - `:incomplete` - - `message: String` + - `class ApplyPatchCall` - Details about the pending safety check. + A tool call representing a request to create, delete, or update files using diff patches. - - `status: :in_progress | :completed | :incomplete` + - `call_id: String` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique ID of the apply patch tool call generated by the model. - - `:in_progress` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `:completed` + The specific create, delete, or update instruction for the apply_patch tool call. - - `:incomplete` + - `class CreateFile` - - `type: :computer_call` + Instruction for creating a new file via the apply_patch tool. - The type of the computer call. Always `computer_call`. + - `diff: String` - - `:computer_call` + Unified diff content to apply when creating the file. - - `action: BetaComputerAction` + - `path: String` - A click action. + Path of the file to create relative to the workspace root. - - `class Click` + - `type: :create_file` - A click action. + The operation type. Always `create_file`. - - `button: :left | :right | :wheel | 2 more` + - `:create_file` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class DeleteFile` - - `:left` + Instruction for deleting an existing file via the apply_patch tool. - - `:right` + - `path: String` - - `:wheel` + Path of the file to delete relative to the workspace root. - - `:back` + - `type: :delete_file` - - `:forward` + The operation type. Always `delete_file`. - - `type: :click` + - `:delete_file` - Specifies the event type. For a click action, this property is always `click`. + - `class UpdateFile` - - `:click` + Instruction for updating an existing file via the apply_patch tool. - - `x: Integer` + - `diff: String` - The x-coordinate where the click occurred. + Unified diff content to apply to the existing file. - - `y_: Integer` + - `path: String` - The y-coordinate where the click occurred. + Path of the file to update relative to the workspace root. - - `keys: Array[String]` + - `type: :update_file` - The keys being held while clicking. + The operation type. Always `update_file`. - - `class DoubleClick` + - `:update_file` - A double click action. + - `status: :in_progress | :completed` - - `keys: Array[String]` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The keys being held while double-clicking. + - `:in_progress` - - `type: :double_click` + - `:completed` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `type: :apply_patch_call` - - `:double_click` + The type of the item. Always `apply_patch_call`. - - `x: Integer` + - `:apply_patch_call` - The x-coordinate where the double click occurred. + - `id: String` - - `y_: Integer` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The y-coordinate where the double click occurred. + - `agent: Agent{ agent_name}` - - `class Drag` + The agent that produced this item. - A drag action. + - `agent_name: String` - - `path: Array[Path{ x, y_}]` + The canonical name of the agent that produced this item. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `caller_: Direct{ type} | Program{ caller_id, type}` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The execution context that produced this tool call. - - `x: Integer` + - `class Direct` - The x-coordinate. + - `type: :direct` - - `y_: Integer` + The caller type. Always `direct`. - The y-coordinate. + - `:direct` - - `type: :drag` + - `class Program` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `caller_id: String` - - `:drag` + The call ID of the program item that produced this tool call. - - `keys: Array[String]` + - `type: :program` - The keys being held while dragging the mouse. + The caller type. Always `program`. - - `class Keypress` + - `:program` - A collection of keypresses the model would like to perform. + - `class ApplyPatchCallOutput` - - `keys: Array[String]` + The streamed output emitted by an apply patch tool call. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `call_id: String` - - `type: :keypress` + The unique ID of the apply patch tool call generated by the model. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `status: :completed | :failed` - - `:keypress` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `class Move` + - `:completed` - A mouse move action. + - `:failed` - - `type: :move` + - `type: :apply_patch_call_output` - Specifies the event type. For a move action, this property is always set to `move`. + The type of the item. Always `apply_patch_call_output`. - - `:move` + - `:apply_patch_call_output` - - `x: Integer` + - `id: String` - The x-coordinate to move to. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `y_: Integer` + - `agent: Agent{ agent_name}` - The y-coordinate to move to. + The agent that produced this item. - - `keys: Array[String]` + - `agent_name: String` - The keys being held while moving the mouse. + The canonical name of the agent that produced this item. - - `class Screenshot` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A screenshot action. + The execution context that produced this tool call. - - `type: :screenshot` + - `class Direct` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `type: :direct` - - `:screenshot` + The caller type. Always `direct`. - - `class Scroll` + - `:direct` - A scroll action. + - `class Program` - - `scroll_x: Integer` + - `caller_id: String` - The horizontal scroll distance. + The call ID of the program item that produced this tool call. - - `scroll_y: Integer` + - `type: :program` - The vertical scroll distance. + The caller type. Always `program`. - - `type: :scroll` + - `:program` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `output: String` - - `:scroll` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `x: Integer` + - `class McpListTools` - The x-coordinate where the scroll occurred. + A list of tools available on an MCP server. - - `y_: Integer` + - `id: String` - The y-coordinate where the scroll occurred. + The unique ID of the list. - - `keys: Array[String]` + - `server_label: String` - The keys being held while scrolling. + The label of the MCP server. - - `class Type` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - An action to type in text. + The tools available on the server. - - `text: String` + - `input_schema: untyped` - The text to type. + The JSON schema describing the tool's input. - - `type: :type` + - `name: String` - Specifies the event type. For a type action, this property is always set to `type`. + The name of the tool. - - `:type` + - `annotations: untyped` - - `class Wait` + Additional annotations about the tool. - A wait action. + - `description: String` - - `type: :wait` + The description of the tool. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `type: :mcp_list_tools` - - `:wait` + The type of the item. Always `mcp_list_tools`. - - `actions: BetaComputerActionList` + - `:mcp_list_tools` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `agent: Agent{ agent_name}` - - `class Click` + The agent that produced this item. - A click action. + - `agent_name: String` - - `class DoubleClick` + The canonical name of the agent that produced this item. - A double click action. + - `error: String` - - `class Drag` + Error message if the server could not list tools. - A drag action. + - `class McpApprovalRequest` - - `class Keypress` + A request for human approval of a tool invocation. - A collection of keypresses the model would like to perform. + - `id: String` - - `class Move` + The unique ID of the approval request. - A mouse move action. + - `arguments: String` - - `class Screenshot` + A JSON string of arguments for the tool. - A screenshot action. + - `name: String` - - `class Scroll` + The name of the tool to run. - A scroll action. + - `server_label: String` - - `class Type` + The label of the MCP server making the request. - An action to type in text. + - `type: :mcp_approval_request` - - `class Wait` + The type of the item. Always `mcp_approval_request`. - A wait action. + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -125149,207 +137854,201 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput` - - The output of a computer tool call. + - `class McpApprovalResponse` - - `call_id: String` + A response to an MCP approval request. - The ID of the computer tool call that produced the output. + - `approval_request_id: String` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The ID of the approval request being answered. - A computer screenshot image used with the computer use tool. + - `approve: bool` - - `type: :computer_screenshot` + Whether the request was approved. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `type: :mcp_approval_response` - - `:computer_screenshot` + The type of the item. Always `mcp_approval_response`. - - `file_id: String` + - `:mcp_approval_response` - The identifier of an uploaded file that contains the screenshot. + - `id: String` - - `image_url: String` + The unique ID of the approval response - The URL of the screenshot image. + - `agent: Agent{ agent_name}` - - `type: :computer_call_output` + The agent that produced this item. - The type of the computer tool call output. Always `computer_call_output`. + - `agent_name: String` - - `:computer_call_output` + The canonical name of the agent that produced this item. - - `id: String` + - `reason: String` - The ID of the computer tool call output. + Optional reason for the decision. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `class McpCall` - The safety checks reported by the API that have been acknowledged by the developer. + An invocation of a tool on an MCP server. - `id: String` - The ID of the pending safety check. - - - `code: String` + The unique ID of the tool call. - The type of the pending safety check. + - `arguments: String` - - `message: String` + A JSON string of the arguments passed to the tool. - Details about the pending safety check. + - `name: String` - - `agent: Agent{ agent_name}` + The name of the tool that was run. - The agent that produced this item. + - `server_label: String` - - `agent_name: String` + The label of the MCP server running the tool. - The canonical name of the agent that produced this item. + - `type: :mcp_call` - - `status: :in_progress | :completed | :incomplete` + The type of the item. Always `mcp_call`. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `:mcp_call` - - `:in_progress` + - `agent: Agent{ agent_name}` - - `:completed` + The agent that produced this item. - - `:incomplete` + - `agent_name: String` - - `class BetaResponseFunctionWebSearch` + The canonical name of the agent that produced this item. - 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. + - `approval_request_id: String` - - `id: String` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The unique ID of the web search tool call. + - `error: String` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + The error from the tool call, if any. - 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). + - `output: String` - - `class Search` + The output from the tool call. - Action type "search" - Performs a web search query. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `type: :search` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The action type. + - `:in_progress` - - `:search` + - `:completed` - - `queries: Array[String]` + - `:incomplete` - The search queries. + - `:calling` - - `query: String` + - `:failed` - The search query. + - `class BetaResponseCustomToolCallOutput` - - `sources: Array[Source{ type, url}]` + The output of a custom tool call from your code, being sent back to the model. - The sources used in the search. + - `call_id: String` - - `type: :url` + The call ID, used to map this custom tool call output to a custom tool call. - The type of source. Always `url`. + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `:url` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `url: String` + - `String = String` - The URL of the source. + A string of the output of the custom tool call. - - `class OpenPage` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - Action type "open_page" - Opens a specific URL from search results. + Text, image, or file output of the custom tool call. - - `type: :open_page` + - `class BetaResponseInputText` - The action type. + A text input to the model. - - `:open_page` + - `class BetaResponseInputImage` - - `url: String` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The URL opened by the model. + - `class BetaResponseInputFile` - - `class FindInPage` + A file input to the model. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: :custom_tool_call_output` - - `pattern: String` + The type of the custom tool call output. Always `custom_tool_call_output`. - The pattern or text to search for within the page. + - `:custom_tool_call_output` - - `type: :find_in_page` + - `id: String` - The action type. + The unique ID of the custom tool call output in the OpenAI platform. - - `:find_in_page` + - `agent: Agent{ agent_name}` - - `url: String` + The agent that produced this item. - The URL of the page searched for the pattern. + - `agent_name: String` - - `status: :in_progress | :searching | :completed | :failed` + The canonical name of the agent that produced this item. - The status of the web search tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:in_progress` + The execution context that produced this tool call. - - `:searching` + - `class Direct` - - `:completed` + - `type: :direct` - - `:failed` + The caller type. Always `direct`. - - `type: :web_search_call` + - `:direct` - The type of the web search tool call. Always `web_search_call`. + - `class Program` - - `:web_search_call` + - `caller_id: String` - - `agent: Agent{ 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` - - `class BetaResponseFunctionToolCall` + - `class BetaResponseCustomToolCall` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A call to a custom tool created by the model. - - `arguments: String` + - `call_id: String` - A JSON string of the arguments to pass to the function. + An identifier used to map this custom tool call to a tool call output. - - `call_id: String` + - `input: String` - The unique ID of the function tool call generated by the model. + The input for the custom tool call generated by the model. - `name: String` - The name of the function to run. + The name of the custom tool being called. - - `type: :function_call` + - `type: :custom_tool_call` - The type of the function tool call. Always `function_call`. + The type of the custom tool call. Always `custom_tool_call`. - - `:function_call` + - `:custom_tool_call` - `id: String` - The unique ID of the function tool call. + The unique ID of the custom tool call in the OpenAI platform. - `agent: Agent{ agent_name}` @@ -125381,1578 +138080,1576 @@ puts(beta_compacted_response) - `namespace: String` - The namespace of the function to run. + The namespace of the custom tool being called. - - `status: :in_progress | :completed | :incomplete` + - `class CompactionTrigger` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Compacts the current context. Must be the final input item. - - `:in_progress` + - `type: :compaction_trigger` - - `:completed` + The type of the item. Always `compaction_trigger`. - - `:incomplete` + - `:compaction_trigger` - - `class FunctionCallOutput` + - `agent: Agent{ agent_name}` - The output of a function tool call. + The agent that produced this item. - - `call_id: String` + - `agent_name: String` - The unique ID of the function tool call generated by the model. + The canonical name of the agent that produced this item. - - `output: String | BetaResponseFunctionCallOutputItemList` + - `class ItemReference` - Text, image, or file output of the function tool call. + An internal identifier for an item to reference. - - `String = String` + - `id: String` - A JSON string of the output of the function tool call. + The ID of the item to reference. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `agent: Agent{ agent_name}` - An array of content outputs (text, image, file) for the function tool call. + The agent that produced this item. - - `class BetaResponseInputTextContent` + - `agent_name: String` - A text input to the model. + The canonical name of the agent that produced this item. - - `text: String` + - `type: :item_reference` - The text input to the model. + The type of item to reference. Always `item_reference`. - - `type: :input_text` + - `:item_reference` - The type of the input item. Always `input_text`. + - `class Program` - - `:input_text` + - `id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The unique ID of this program 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. + - `call_id: String` - - `mode: :explicit` + The stable call ID of the program item. - The breakpoint mode. Always `explicit`. + - `code: String` - - `:explicit` + The JavaScript source executed by programmatic tool calling. - - `class BetaResponseInputImageContent` + - `fingerprint: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + 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` - - `detail: :low | :high | :auto | :original` + - `agent: Agent{ agent_name}` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `:low` + - `agent_name: String` - - `:high` + The canonical name of the agent that produced this item. - - `:auto` + - `class ProgramOutput` - - `:original` + - `id: String` - - `file_id: String` + The unique ID of this program output item. - The ID of the file to be sent to the model. + - `call_id: String` - - `image_url: String` + The call ID of the program item. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `result: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The result produced by the program 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. + - `status: :completed | :incomplete` - - `mode: :explicit` + The terminal status of the program output. - The breakpoint mode. Always `explicit`. + - `:completed` - - `:explicit` + - `:incomplete` - - `class BetaResponseInputFileContent` + - `type: :program_output` - A file input to the model. + The item type. Always `program_output`. - - `type: :input_file` + - `:program_output` - The type of the input item. Always `input_file`. + - `agent: Agent{ agent_name}` - - `:input_file` + The agent that produced this item. - - `detail: :auto | :low | :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` + - `metadata: Hash[Symbol, String]` - - `: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. - - `:high` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `file_data: String` + - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` - The base64-encoded data of the file to be sent to the model. + 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. - - `file_id: String` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` - The ID of the file to be sent to the model. + 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. - - `file_url: String` + - `:"gpt-5.6-sol"` - The URL of the file to be sent to the model. + - `:"gpt-5.6-terra"` - - `filename: String` + - `:"gpt-5.6-luna"` - The name of the file to be sent to the model. + - `:"gpt-5.4"` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"gpt-5.4-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-5.4-nano"` - - `mode: :explicit` + - `:"gpt-5.4-mini-2026-03-17"` - The breakpoint mode. Always `explicit`. + - `:"gpt-5.4-nano-2026-03-17"` - - `:explicit` + - `:"gpt-5.3-chat-latest"` - - `type: :function_call_output` + - `:"gpt-5.2"` - The type of the function tool call output. Always `function_call_output`. + - `:"gpt-5.2-2025-12-11"` - - `:function_call_output` + - `:"gpt-5.2-chat-latest"` - - `id: String` + - `:"gpt-5.2-pro"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `:"gpt-5.2-pro-2025-12-11"` - - `agent: Agent{ agent_name}` + - `:"gpt-5.1"` - The agent that produced this item. + - `:"gpt-5.1-2025-11-13"` - - `agent_name: String` + - `:"gpt-5.1-codex"` - The canonical name of the agent that produced this item. + - `:"gpt-5.1-mini"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-5.1-chat-latest"` - The execution context that produced this tool call. + - `:"gpt-5"` - - `class Direct` + - `:"gpt-5-mini"` - - `type: :direct` + - `:"gpt-5-nano"` - The caller type. Always `direct`. + - `:"gpt-5-2025-08-07"` - - `:direct` + - `:"gpt-5-mini-2025-08-07"` - - `class Program` + - `:"gpt-5-nano-2025-08-07"` - - `caller_id: String` + - `:"gpt-5-chat-latest"` - The call ID of the program item that produced this tool call. + - `:"gpt-4.1"` - - `type: :program` + - `:"gpt-4.1-mini"` - The caller type. Always `program`. + - `:"gpt-4.1-nano"` - - `:program` + - `:"gpt-4.1-2025-04-14"` - - `status: :in_progress | :completed | :incomplete` + - `:"gpt-4.1-mini-2025-04-14"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `:"gpt-4.1-nano-2025-04-14"` - - `:in_progress` + - `:"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"` - - `:completed` + - `:"o1-preview-2024-09-12"` - - `:incomplete` + - `:"o1-mini"` - - `class AgentMessage` + - `:"o1-mini-2024-09-12"` - A message routed between agents. + - `:"gpt-4o"` - - `author: String` + - `:"gpt-4o-2024-11-20"` - The sending agent identity. + - `:"gpt-4o-2024-08-06"` - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + - `:"gpt-4o-2024-05-13"` - Plaintext, image, or encrypted content sent between agents. + - `:"gpt-4o-audio-preview"` - - `class BetaResponseInputTextContent` + - `:"gpt-4o-audio-preview-2024-10-01"` - A text input to the model. + - `:"gpt-4o-audio-preview-2024-12-17"` - - `class BetaResponseInputImageContent` + - `:"gpt-4o-audio-preview-2025-06-03"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:"gpt-4o-mini-audio-preview"` - - `class EncryptedContent` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `:"gpt-4o-search-preview"` - - `encrypted_content: String` + - `:"gpt-4o-mini-search-preview"` - Opaque encrypted content. + - `:"gpt-4o-search-preview-2025-03-11"` - - `type: :encrypted_content` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - The type of the input item. Always `encrypted_content`. + - `:"chatgpt-4o-latest"` - - `:encrypted_content` + - `:"codex-mini-latest"` - - `recipient: String` + - `:"gpt-4o-mini"` - The destination agent identity. + - `:"gpt-4o-mini-2024-07-18"` - - `type: :agent_message` + - `:"gpt-4-turbo"` - The item type. Always `agent_message`. + - `:"gpt-4-turbo-2024-04-09"` - - `:agent_message` + - `:"gpt-4-0125-preview"` - - `id: String` + - `:"gpt-4-turbo-preview"` - The unique ID of this agent message item. + - `:"gpt-4-1106-preview"` - - `agent: Agent{ agent_name}` + - `:"gpt-4-vision-preview"` - The agent that produced this item. + - `:"gpt-4"` - - `agent_name: String` + - `:"gpt-4-0314"` - The canonical name of the agent that produced this item. + - `:"gpt-4-0613"` - - `class MultiAgentCall` + - `:"gpt-4-32k"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:"gpt-4-32k-0314"` - The multi-agent action that was executed. + - `:"gpt-4-32k-0613"` - - `:spawn_agent` + - `:"gpt-3.5-turbo"` - - `:interrupt_agent` + - `:"gpt-3.5-turbo-16k"` - - `:list_agents` + - `:"gpt-3.5-turbo-0301"` - - `:send_message` + - `:"gpt-3.5-turbo-0613"` - - `:followup_task` + - `:"gpt-3.5-turbo-1106"` - - `:wait_agent` + - `:"gpt-3.5-turbo-0125"` - - `arguments: String` + - `:"gpt-3.5-turbo-16k-0613"` - The action arguments as a JSON string. + - `:"o1-pro"` - - `call_id: String` + - `:"o1-pro-2025-03-19"` - The unique ID linking this call to its output. + - `:"o3-pro"` - - `type: :multi_agent_call` + - `:"o3-pro-2025-06-10"` - The item type. Always `multi_agent_call`. + - `:"o3-deep-research"` - - `:multi_agent_call` + - `:"o3-deep-research-2025-06-26"` - - `id: String` + - `:"o4-mini-deep-research"` - The unique ID of this multi-agent call. + - `:"o4-mini-deep-research-2025-06-26"` - - `agent: Agent{ agent_name}` + - `:"computer-use-preview"` - The agent that produced this item. + - `:"computer-use-preview-2025-03-11"` - - `agent_name: String` + - `:"gpt-5-codex"` - The canonical name of the agent that produced this item. + - `:"gpt-5-pro"` - - `class MultiAgentCallOutput` + - `:"gpt-5-pro-2025-10-06"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:"gpt-5.1-codex-max"` - The multi-agent action that produced this result. + - `String = String` - - `:spawn_agent` + - `object: :response` - - `:interrupt_agent` + The object type of this resource - always set to `response`. - - `:list_agents` + - `:response` - - `:send_message` + - `output: Array[BetaResponseOutputItem]` - - `:followup_task` + An array of content items generated by the model. - - `:wait_agent` + - 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. - - `call_id: String` + - `class BetaResponseOutputMessage` - The unique ID of the multi-agent call. + An output message from the model. - - `output: Array[Output{ text, type, annotations}]` + - `class BetaResponseFileSearchToolCall` - Text output returned by the multi-agent action. + 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. - - `text: String` + - `class BetaResponseFunctionToolCall` - The text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `type: :output_text` + - `class BetaResponseFunctionToolCallOutputItem` - The content type. Always `output_text`. + - `id: String` - - `:output_text` + The unique ID of the function call tool output. - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `call_id: String` - Citations associated with the text content. + The unique ID of the function tool call generated by the model. - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `file_id: String` + The output from the function call generated by your code. + Can be a string or an list of output content. - The ID of the file. + - `String = String` - - `filename: String` + A string of the output of the function call. - The filename of the file cited. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `index: Integer` + Text, image, or file output of the function call. - The index of the file in the list of files. + - `class BetaResponseInputText` - - `type: :file_citation` + A text input to the model. - The citation type. Always `file_citation`. + - `class BetaResponseInputImage` - - `:file_citation` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `class BetaResponseInputFile` - - `end_index: Integer` + A file input to the model. - The index of the last character of the citation in the message. + - `status: :in_progress | :completed | :incomplete` - - `start_index: Integer` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The index of the first character of the citation in the message. + - `:in_progress` - - `title: String` + - `:completed` - The title of the cited resource. + - `:incomplete` - - `type: :url_citation` + - `type: :function_call_output` - The citation type. Always `url_citation`. + The type of the function tool call output. Always `function_call_output`. - - `:url_citation` + - `:function_call_output` - - `url: String` + - `agent: Agent{ agent_name}` - The URL of the cited resource. + The agent that produced this item. - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `agent_name: String` - - `container_id: String` + The canonical name of the agent that produced this item. - The ID of the container. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `end_index: Integer` + The execution context that produced this tool call. - The index of the last character of the citation in the message. + - `class Direct` - - `file_id: String` + - `type: :direct` - The ID of the container file. + The caller type. Always `direct`. - - `filename: String` + - `:direct` - The filename of the container file cited. + - `class Program` - - `start_index: Integer` + - `caller_id: String` - The index of the first character of the citation in the message. + The call ID of the program item that produced this tool call. - - `type: :container_file_citation` + - `type: :program` - The citation type. Always `container_file_citation`. + The caller type. Always `program`. - - `:container_file_citation` + - `:program` - - `type: :multi_agent_call_output` + - `created_by: String` - The item type. Always `multi_agent_call_output`. + The identifier of the actor that created the item. - - `:multi_agent_call_output` + - `class AgentMessage` - `id: String` - The unique ID of this multi-agent call output. + The unique ID of the agent message. - - `agent: Agent{ agent_name}` + - `author: String` - The agent that produced this item. + The sending agent identity. - - `agent_name: String` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - The canonical name of the agent that produced this item. + Encrypted content sent between agents. - - `class ToolSearchCall` + - `class BetaResponseInputText` - - `arguments: untyped` + A text input to the model. - The arguments supplied to the tool search call. + - `class BetaResponseOutputText` - - `type: :tool_search_call` + A text output from the model. - The item type. Always `tool_search_call`. + - `class Text` - - `:tool_search_call` + A text content. - - `id: String` + - `text: String` - The unique ID of this tool search call. + - `type: :text` - - `agent: Agent{ agent_name}` + - `:text` - The agent that produced this item. + - `class SummaryText` - - `agent_name: String` + A summary text from the model. - The canonical name of the agent that produced this item. + - `text: String` - - `call_id: String` + A summary of the reasoning output from the model so far. - The unique ID of the tool search call generated by the model. + - `type: :summary_text` - - `execution: :server | :client` + The type of the object. Always `summary_text`. - Whether tool search was executed by the server or by the client. + - `:summary_text` - - `:server` + - `class ReasoningText` - - `:client` + Reasoning text from the model. - - `status: :in_progress | :completed | :incomplete` + - `text: String` - The status of the tool search call. + The reasoning text from the model. - - `:in_progress` + - `type: :reasoning_text` - - `:completed` + The type of the reasoning text. Always `reasoning_text`. - - `:incomplete` + - `:reasoning_text` - - `class BetaResponseToolSearchOutputItemParam` + - `class BetaResponseOutputRefusal` - - `tools: Array[BetaTool]` + A refusal from the model. - The loaded tool definitions returned by the tool search output. + - `class BetaResponseInputImage` - - `class BetaFunctionTool` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - 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). + - `class ComputerScreenshot` - - `name: String` + A screenshot of a computer. - The name of the function to call. + - `detail: :low | :high | :auto | :original` - - `parameters: Hash[Symbol, untyped]` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A JSON schema object describing the parameters of the function. + - `:low` - - `strict: bool` + - `:high` - Whether strict parameter validation is enforced for this function tool. + - `:auto` - - `type: :function` + - `:original` - The type of the function tool. Always `function`. + - `file_id: String` - - `:function` + The identifier of an uploaded file that contains the screenshot. - - `allowed_callers: Array[:direct | :programmatic]` + - `image_url: String` - The tool invocation context(s). + The URL of the screenshot image. - - `:direct` + - `type: :computer_screenshot` - - `:programmatic` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `defer_loading: bool` + - `:computer_screenshot` - Whether this function is deferred and loaded via tool search. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `description: 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. - A description of the function. Used by the model to determine whether or not to call the function. + - `mode: :explicit` - - `output_schema: Hash[Symbol, untyped]` + The breakpoint mode. Always `explicit`. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `:explicit` - - `class BetaFileSearchTool` + - `class BetaResponseInputFile` - 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 file input to the model. - - `type: :file_search` + - `class EncryptedContent` - The type of the file search tool. Always `file_search`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `:file_search` + - `encrypted_content: String` - - `vector_store_ids: Array[String]` + Opaque encrypted content. - The IDs of the vector stores to search. + - `type: :encrypted_content` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + The type of the input item. Always `encrypted_content`. - A filter to apply. + - `:encrypted_content` - - `class ComparisonFilter` + - `recipient: String` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The destination agent identity. - - `key: String` + - `type: :agent_message` - The key to compare against the value. + The type of the item. Always `agent_message`. - - `type: :eq | :ne | :gt | 5 more` + - `:agent_message` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent: Agent{ 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` + - `class MultiAgentCall` - - `:gte` + - `id: String` - - `:lt` + The unique ID of the multi-agent call item. - - `:lte` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:in` + The multi-agent action to execute. - - `:nin` + - `:spawn_agent` - - `value: String | Float | bool | Array[untyped]` + - `:interrupt_agent` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:list_agents` - - `String = String` + - `:send_message` - - `Float = Float` + - `:followup_task` - - `UnionMember2 = bool` + - `:wait_agent` - - `UnionMember3 = Array[untyped]` + - `arguments: String` - - `class CompoundFilter` + The JSON string of arguments generated for the action. - Combine multiple filters using `and` or `or`. + - `call_id: String` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + The unique ID linking this call to its output. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `type: :multi_agent_call` - - `class ComparisonFilter` + The type of the multi-agent call. Always `multi_agent_call`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `:multi_agent_call` - - `key: String` + - `agent: Agent{ agent_name}` - The key to compare against the value. + The agent that produced this item. - - `type: :eq | :ne | :gt | 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 + - `class MultiAgentCallOutput` - - `:eq` + - `id: String` - - `:ne` + The unique ID of the multi-agent call output item. - - `:gt` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `:gte` + The multi-agent action that produced this result. - - `:lt` + - `:spawn_agent` - - `:lte` + - `:interrupt_agent` - - `:in` + - `:list_agents` - - `:nin` + - `:send_message` - - `value: String | Float | bool | Array[untyped]` + - `:followup_task` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:wait_agent` - - `String = String` + - `call_id: String` - - `Float = Float` + The unique ID of the multi-agent call. - - `UnionMember2 = bool` + - `output: Array[BetaResponseOutputText]` - - `UnionMember3 = Array[untyped]` + Text output returned by the multi-agent action. - - `UnionMember1 = untyped` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `type: :and | :or` + The annotations of the text output. - Type of operation: `and` or `or`. + - `text: String` - - `:and` + The text output from the model. - - `:or` + - `type: :output_text` - - `max_num_results: Integer` + The type of the output text. Always `output_text`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `type: :multi_agent_call_output` - Ranking options for search. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `:multi_agent_call_output` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `agent: Agent{ agent_name}` - - `embedding_weight: Float` + The agent that produced this item. - The weight of the embedding in the reciprocal ranking fusion. + - `agent_name: String` - - `text_weight: Float` + The canonical name of the agent that produced this item. - The weight of the text in the reciprocal ranking fusion. + - `class BetaResponseFunctionWebSearch` - - `ranker: :auto | :"default-2024-11-15"` + 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 ranker to use for the file search. + - `class BetaResponseComputerToolCall` - - `:auto` + 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. - - `:"default-2024-11-15"` + - `class BetaResponseComputerToolCallOutputItem` - - `score_threshold: Float` + - `id: String` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The unique ID of the computer call tool output. - - `class BetaComputerTool` + - `call_id: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the computer tool call that produced the output. - - `type: :computer` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The type of the computer tool. Always `computer`. + A computer screenshot image used with the computer use tool. - - `:computer` + - `status: :completed | :incomplete | :failed | :in_progress` - - `class BetaComputerUsePreviewTool` + 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). + - `:completed` - - `display_height: Integer` + - `:incomplete` - The height of the computer display. + - `:failed` - - `display_width: Integer` + - `:in_progress` - The width of the computer display. + - `type: :computer_call_output` - - `environment: :windows | :mac | :linux | 2 more` + The type of the computer tool call output. Always `computer_call_output`. - The type of computer environment to control. + - `:computer_call_output` - - `:windows` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `:mac` + The safety checks reported by the API that have been acknowledged by the + developer. - - `:linux` + - `id: String` - - `:ubuntu` + The ID of the pending safety check. - - `:browser` + - `code: String` - - `type: :computer_use_preview` + The type of the pending safety check. - The type of the computer use tool. Always `computer_use_preview`. + - `message: String` - - `:computer_use_preview` + Details about the pending safety check. - - `class BetaWebSearchTool` + - `agent: Agent{ agent_name}` - 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 agent that produced this item. - - `type: :web_search | :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` + - `created_by: String` - - `:web_search_2025_08_26` + The identifier of the actor that created the item. - - `filters: Filters{ allowed_domains}` + - `class BetaResponseReasoningItem` - Filters for the search. + 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). - - `allowed_domains: Array[String]` + - `class Program` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `id: String` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The unique ID of the program item. - - `search_context_size: :low | :medium | :high` + - `call_id: String` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The stable call ID of the program item. - - `:low` + - `code: String` - - `:medium` + The JavaScript source executed by programmatic tool calling. - - `:high` + - `fingerprint: String` - - `user_location: UserLocation{ city, country, region, 2 more}` + Opaque program replay fingerprint that must be round-tripped. - The approximate location of the user. + - `type: :program` - - `city: String` + The type of the item. Always `program`. - Free text input for the city of the user, e.g. `San Francisco`. + - `:program` - - `country: String` + - `agent: Agent{ 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: 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: String` + - `class ProgramOutput` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `id: String` - - `type: :approximate` + The unique ID of the program output item. - The type of location approximation. Always `approximate`. + - `call_id: String` - - `:approximate` + The call ID of the program item. - - `class Mcp` + - `result: 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 result produced by the program item. - - `server_label: String` + - `status: :completed | :incomplete` - A label for this MCP server, used to identify it in tool calls. + The terminal status of the program output item. - - `type: :mcp` + - `:completed` - The type of the MCP tool. Always `mcp`. + - `:incomplete` - - `:mcp` + - `type: :program_output` - - `allowed_callers: Array[:direct | :programmatic]` + The type of the item. Always `program_output`. - The tool invocation context(s). + - `:program_output` - - `:direct` + - `agent: Agent{ agent_name}` - - `:programmatic` + The agent that produced this item. - - `allowed_tools: Array[String] | McpToolFilter{ 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[String]` + - `class BetaResponseToolSearchCall` - A string array of allowed tool names + - `id: String` - - `class McpToolFilter` + The unique ID of the tool search call item. - A filter object to specify which tools are allowed. + - `arguments: untyped` - - `read_only: bool` + Arguments used for the tool search call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `call_id: String` - - `tool_names: Array[String]` + The unique ID of the tool search call generated by the model. - List of allowed tool names. + - `execution: :server | :client` - - `authorization: String` + Whether tool search was executed by the server or by the client. - 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. + - `:server` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:client` - 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 | :completed | :incomplete` - Currently supported `connector_id` values are: + The status of the tool search call item that was recorded. - - 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: :tool_search_call` - - `:connector_googledrive` + The type of the item. Always `tool_search_call`. - - `:connector_microsoftteams` + - `:tool_search_call` - - `:connector_outlookcalendar` + - `agent: Agent{ agent_name}` - - `:connector_outlookemail` + The agent that produced this item. - - `:connector_sharepoint` + - `agent_name: String` - - `defer_loading: bool` + The canonical name of the agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `created_by: String` - - `headers: Hash[Symbol, String]` + The identifier of the actor that created the item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `class BetaResponseToolSearchOutputItem` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `id: String` - Specify which of the MCP server's tools require approval. + The unique ID of the tool search output item. - - `class McpToolApprovalFilter` + - `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 tool search call generated by the model. - - `always: Always{ read_only, tool_names}` + - `execution: :server | :client` - A filter object to specify which tools are allowed. + Whether tool search was executed by the server or by the client. - - `read_only: bool` + - `: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. + - `:client` - - `tool_names: Array[String]` + - `status: :in_progress | :completed | :incomplete` - List of allowed tool names. + The status of the tool search output item that was recorded. - - `never: Never{ read_only, tool_names}` + - `:in_progress` - A filter object to specify which tools are allowed. + - `:completed` - - `read_only: bool` + - `: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. + - `tools: Array[BetaTool]` - - `tool_names: Array[String]` + The loaded tool definitions returned by tool search. - List of allowed tool names. + - `class BetaFunctionTool` - - `McpToolApprovalSetting = :always | :never` + 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). - 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. + - `class BetaFileSearchTool` - - `:always` + 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). - - `:never` + - `class BetaComputerTool` - - `server_description: String` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Optional description of the MCP server, used to provide more context. + - `class BetaComputerUsePreviewTool` - - `server_url: String` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `class BetaWebSearchTool` - - `tunnel_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 Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `class Mcp` + + 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). - `class CodeInterpreter` A tool that runs Python code to help generate a response to a prompt. - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `class ProgrammaticToolCalling` - 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. + - `class ImageGeneration` - - `String = String` + A tool that generates images using the GPT image models. - The container ID. + - `class LocalShell` - - `class CodeInterpreterToolAuto` + A tool that allows the model to execute shell commands in a local environment. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `class BetaFunctionShellTool` - - `type: :auto` + A tool that allows the model to execute shell commands. - Always `auto`. + - `class BetaCustomTool` - - `: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: Array[String]` + - `class BetaNamespaceTool` - An optional list of uploaded files to make available to your code. + Groups function/custom tools under a shared namespace. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class BetaToolSearchTool` - The memory limit for the code interpreter container. + Hosted or BYOT tool search configuration for deferred tools. - - `:"1g"` + - `class BetaWebSearchPreviewTool` - - `:"4g"` + 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). - - `:"16g"` + - `class BetaApplyPatchTool` - - `:"64g"` + Allows the assistant to create, delete, or update files using unified diffs. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :tool_search_output` - Network access policy for the container. + The type of the item. Always `tool_search_output`. - - `class BetaContainerNetworkPolicyDisabled` + - `:tool_search_output` - - `type: :disabled` + - `agent: Agent{ agent_name}` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `:disabled` + - `agent_name: String` - - `class BetaContainerNetworkPolicyAllowlist` + The canonical name of the agent that produced this item. - - `allowed_domains: Array[String]` + - `created_by: String` - A list of allowed domains when type is `allowlist`. + The identifier of the actor that created the item. - - `type: :allowlist` + - `class AdditionalTools` - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: String` - - `:allowlist` + The unique ID of the additional tools item. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `role: :unknown | :user | :assistant | 5 more` - Optional domain-scoped secrets for allowlisted domains. + The role that provided the additional tools. - - `domain: String` + - `:unknown` - The domain associated with the secret. + - `:user` - - `name: String` + - `:assistant` - The name of the secret to inject for the domain. + - `:system` - - `value: String` + - `:critic` - The secret value to inject for the domain. + - `:discriminator` - - `type: :code_interpreter` + - `:developer` - The type of the code interpreter tool. Always `code_interpreter`. + - `:tool` - - `:code_interpreter` + - `tools: Array[BetaTool]` - - `allowed_callers: Array[:direct | :programmatic]` + The additional tool definitions made available at this item. - The tool invocation context(s). + - `class BetaFunctionTool` - - `: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` + - `class BetaFileSearchTool` - - `class ProgrammaticToolCalling` + 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: :programmatic_tool_calling` + - `class BetaComputerTool` - The type of the tool. Always `programmatic_tool_calling`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:programmatic_tool_calling` + - `class BetaComputerUsePreviewTool` - - `class ImageGeneration` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A tool that generates images using the GPT image models. + - `class BetaWebSearchTool` - - `type: :image_generation` + 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 the image generation tool. Always `image_generation`. + - `class Mcp` - - `:image_generation` + 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: :generate | :edit | :auto` + - `class CodeInterpreter` - Whether to generate a new image or edit an existing image. Default: `auto`. + A tool that runs Python code to help generate a response to a prompt. - - `:generate` + - `class ProgrammaticToolCalling` - - `:edit` + - `class ImageGeneration` - - `:auto` + A tool that generates images using the GPT image models. - - `background: :transparent | :opaque | :auto` + - `class LocalShell` - 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 tool that allows the model to execute shell commands in a local environment. - `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. + - `class BetaFunctionShellTool` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + A tool that allows the model to execute shell commands. - - `:transparent` + - `class BetaCustomTool` - - `:opaque` + 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) - - `:auto` + - `class BetaNamespaceTool` - - `input_fidelity: :high | :low` + Groups function/custom tools under a shared namespace. - 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`. + - `class BetaToolSearchTool` - - `:high` + Hosted or BYOT tool search configuration for deferred tools. - - `:low` + - `class BetaWebSearchPreviewTool` - - `input_image_mask: InputImageMask{ file_id, image_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). - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `class BetaApplyPatchTool` - - `file_id: String` + Allows the assistant to create, delete, or update files using unified diffs. - File ID for the mask image. + - `type: :additional_tools` - - `image_url: String` + The type of the item. Always `additional_tools`. - Base64-encoded mask image. + - `:additional_tools` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `agent: Agent{ agent_name}` - The image generation model to use. Default: `gpt-image-1`. + The agent that produced this item. - - `String = String` + - `agent_name: String` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The canonical name of the agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `class BetaResponseCompactionItem` - - `:"gpt-image-1"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `:"gpt-image-1-mini"` + - `id: String` - - `:"gpt-image-2"` + The unique ID of the compaction item. - - `:"gpt-image-2-2026-04-21"` + - `encrypted_content: String` - - `:"gpt-image-1.5"` + The encrypted content that was produced by compaction. - - `:"chatgpt-image-latest"` + - `type: :compaction` - - `moderation: :auto | :low` + The type of the item. Always `compaction`. - Moderation level for the generated image. Default: `auto`. + - `:compaction` - - `:auto` + - `agent: Agent{ agent_name}` - - `:low` + The agent that produced this item. - - `output_compression: Integer` + - `agent_name: String` - Compression level for the output image. Default: 100. + The canonical name of the agent that produced this item. - - `output_format: :png | :webp | :jpeg` + - `created_by: String` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The identifier of the actor that created the item. - - `:png` + - `class ImageGenerationCall` - - `:webp` + An image generation request made by the model. - - `:jpeg` + - `id: String` - - `partial_images: Integer` + The unique ID of the image generation call. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `result: String` - - `quality: :low | :medium | :high | :auto` + The generated image encoded in base64. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `status: :in_progress | :completed | :generating | :failed` - - `:low` + The status of the image generation call. - - `:medium` + - `:in_progress` - - `:high` + - `:completed` - - `:auto` + - `:generating` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `:failed` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: :image_generation_call` - - `String = String` + The type of the image generation call. Always `image_generation_call`. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `:image_generation_call` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `agent: Agent{ 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` + - `class BetaResponseCodeInterpreterToolCall` - - `class LocalShell` + A tool call to run code. - A tool that allows the model to execute shell commands in a local environment. + - `class LocalShellCall` - - `type: :local_shell` + A tool call to run a command on the local shell. - The type of the local shell tool. Always `local_shell`. + - `id: String` - - `:local_shell` + The unique ID of the local shell call. - - `class BetaFunctionShellTool` + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` - A tool that allows the model to execute shell commands. + The command to run. - - `type: :shell` + - `env: Hash[Symbol, String]` - The type of the shell tool. Always `shell`. + Environment variables to set for the command. - - `:shell` + - `type: :exec` - - `allowed_callers: Array[:direct | :programmatic]` + The type of the local shell action. Always `exec`. - The tool invocation context(s). + - `:exec` - - `:direct` + - `timeout_ms: Integer` - - `:programmatic` + Optional timeout in milliseconds for the command. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `user: String` - - `class BetaContainerAuto` + Optional user to run the command as. - - `type: :container_auto` + - `working_directory: String` - Automatically creates a container for this request + Optional working directory to run the command in. - - `:container_auto` + - `call_id: String` - - `file_ids: Array[String]` + The unique ID of the local shell tool call generated by the model. - An optional list of uploaded files to make available to your code. + - `status: :in_progress | :completed | :incomplete` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + The status of the local shell call. - The memory limit for the container. + - `:in_progress` - - `:"1g"` + - `:completed` - - `:"4g"` + - `:incomplete` - - `:"16g"` + - `type: :local_shell_call` - - `:"64g"` + The type of the local shell call. Always `local_shell_call`. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `:local_shell_call` - Network access policy for the container. + - `agent: Agent{ agent_name}` - - `class BetaContainerNetworkPolicyDisabled` + The agent that produced this item. - - `class BetaContainerNetworkPolicyAllowlist` + - `agent_name: String` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + The canonical name of the agent that produced this item. - An optional list of skills referenced by id or inline data. + - `class LocalShellCallOutput` - - `class BetaSkillReference` + The output of a local shell tool call. - - `skill_id: String` + - `id: String` - The ID of the referenced skill. + The unique ID of the local shell tool call generated by the model. - - `type: :skill_reference` + - `output: String` - References a skill created with the /v1/skills endpoint. + A JSON string of the output of the local shell tool call. - - `:skill_reference` + - `type: :local_shell_call_output` - - `version: String` + The type of the local shell tool call output. Always `local_shell_call_output`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `:local_shell_call_output` - - `class BetaInlineSkill` + - `agent: Agent{ 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. + - `status: :in_progress | :completed | :incomplete` - - `source: BetaInlineSkillSource` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Inline skill payload + - `:in_progress` - - `data: String` + - `:completed` - Base64-encoded skill zip bundle. + - `:incomplete` - - `media_type: :"application/zip"` + - `class BetaResponseFunctionShellToolCall` - The media type of the inline skill payload. Must be `application/zip`. + A tool call that executes one or more shell commands in a managed environment. - - `:"application/zip"` + - `id: String` - - `type: :base64` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of the inline skill source. Must be `base64`. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:base64` + The shell commands and limits that describe how to run the tool call. - - `type: :inline` + - `commands: Array[String]` - Defines an inline skill for this request. + - `max_output_length: Integer` - - `:inline` + Optional maximum number of characters to return from each command. - - `class BetaLocalEnvironment` + - `timeout_ms: Integer` - - `type: :local` + Optional timeout in milliseconds for the commands. - Use a local computer environment. + - `call_id: String` - - `:local` + The unique ID of the shell tool call generated by the model. - - `skills: Array[BetaLocalSkill]` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - An optional list of skills. + Represents the use of a local environment to perform shell actions. - - `description: String` + - `class BetaResponseLocalEnvironment` - The description of the skill. + Represents the use of a local environment to perform shell actions. - - `name: String` + - `type: :local` - The name of the skill. + The environment type. Always `local`. - - `path: String` + - `:local` - The path to the directory containing the skill. + - `class BetaResponseContainerReference` - - `class BetaContainerReference` + Represents a container created with /v1/containers. - `container_id: String` - The ID of the referenced container. - - `type: :container_reference` - References a container created with the /v1/containers endpoint + The environment type. Always `container_reference`. - `:container_reference` - - `class BetaCustomTool` + - `status: :in_progress | :completed | :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) + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `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: :shell_call` - - `:custom` + The type of the item. Always `shell_call`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:shell_call` - The tool invocation context(s). + - `agent: Agent{ agent_name}` - - `:direct` + The agent that produced this item. - - `:programmatic` + - `agent_name: String` - - `defer_loading: bool` + The canonical name of the agent that produced this item. - Whether this tool should be deferred and discovered via tool search. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `description: String` + The execution context that produced this tool call. - Optional description of the custom tool, used to provide more context. + - `class Direct` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `type: :direct` - The input format for the custom tool. Default is unconstrained text. + - `:direct` - - `class Text` + - `class Program` - 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` + - `:program` - - `class Grammar` + - `created_by: String` - A grammar defined by the user. + The ID of the entity that created this tool call. - - `definition: String` + - `class BetaResponseFunctionShellToolCallOutput` - The grammar definition. + The output of a shell tool call that was emitted. - - `syntax: :lark | :regex` + - `id: String` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `:lark` + - `call_id: String` - - `:regex` + The unique ID of the shell tool call generated by the model. - - `type: :grammar` + - `max_output_length: Integer` - Grammar format. Always `grammar`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `:grammar` + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `class BetaNamespaceTool` + An array of shell call output contents - Groups function/custom tools under a shared namespace. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `description: String` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - A description of the namespace shown to the model. + - `class Timeout` - - `name: String` + Indicates that the shell call exceeded its configured time limit. - The namespace name used in tool calls (for example, `crm`). + - `type: :timeout` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + The outcome type. Always `timeout`. - The function/custom tools available inside this namespace. + - `:timeout` - - `class Function` + - `class Exit` - - `name: String` + Indicates that the shell commands finished and returned an exit code. - - `type: :function` + - `exit_code: Integer` - - `:function` + Exit code from the shell process. - - `allowed_callers: Array[:direct | :programmatic]` + - `type: :exit` - The tool invocation context(s). + The outcome type. Always `exit`. - - `:direct` + - `:exit` - - `:programmatic` + - `stderr: String` - - `defer_loading: bool` + The standard error output that was captured. - Whether this function should be deferred and discovered via tool search. + - `stdout: String` - - `description: String` + The standard output that was captured. - - `output_schema: Hash[Symbol, untyped]` + - `created_by: String` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The identifier of the actor that created the item. - - `parameters: untyped` + - `status: :in_progress | :completed | :incomplete` - - `strict: bool` + The status of the shell call output. 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` - - `class BetaCustomTool` + - `: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` - - `type: :namespace` + - `type: :shell_call_output` - The type of the tool. Always `namespace`. + The type of the shell call output. Always `shell_call_output`. - - `:namespace` + - `:shell_call_output` - - `class BetaToolSearchTool` + - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - `description: String` + The execution context that produced this tool call. - Description shown to the model for a client-executed tool search tool. + - `class Direct` - - `execution: :server | :client` + - `type: :direct` - Whether tool search is executed by the server or by the client. + - `:direct` - - `:server` + - `class Program` - - `:client` + - `caller_id: String` - - `parameters: untyped` + The call ID of the program item that produced this tool call. - Parameter schema for a client-executed tool search tool. + - `type: :program` - - `class BetaWebSearchPreviewTool` + - `: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: String` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + The identifier of the actor that created the item. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class BetaResponseApplyPatchToolCall` - - `:web_search_preview` + A tool call that applies file diffs by creating, deleting, or updating files. - - `:web_search_preview_2025_03_11` + - `id: String` - - `search_content_types: Array[:text | :image]` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `:text` + - `call_id: String` - - `:image` + The unique ID of the apply patch tool call generated by the model. - - `search_context_size: :low | :medium | :high` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, 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. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `:low` + - `class CreateFile` - - `:medium` + Instruction describing how to create a file via the apply_patch tool. - - `:high` + - `diff: String` - - `user_location: UserLocation{ type, city, country, 2 more}` + Diff to apply. - The user's location. + - `path: String` - - `type: :approximate` + Path of the file to create. - The type of location approximation. Always `approximate`. + - `type: :create_file` - - `:approximate` + Create a new file with the provided diff. - - `city: String` + - `:create_file` - Free text input for the city of the user, e.g. `San Francisco`. + - `class DeleteFile` - - `country: String` + Instruction describing how to delete a file via the apply_patch tool. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `path: String` - - `region: String` + Path of the file to delete. - Free text input for the region of the user, e.g. `California`. + - `type: :delete_file` - - `timezone: String` + Delete the specified file. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:delete_file` - - `class BetaApplyPatchTool` + - `class UpdateFile` - Allows the assistant to create, delete, or update files using unified diffs. + Instruction describing how to update a file via the apply_patch tool. - - `type: :apply_patch` + - `diff: String` - The type of the tool. Always `apply_patch`. + Diff to apply. - - `:apply_patch` + - `path: String` - - `allowed_callers: Array[:direct | :programmatic]` + Path of the file to update. - The tool invocation context(s). + - `type: :update_file` - - `:direct` + Update an existing file with the provided diff. - - `:programmatic` + - `:update_file` - - `type: :tool_search_output` + - `status: :in_progress | :completed` - The item type. Always `tool_search_output`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:tool_search_output` + - `:in_progress` - - `id: String` + - `:completed` - The unique ID of this tool search output. + - `type: :apply_patch_call` + + The type of the item. Always `apply_patch_call`. + + - `:apply_patch_call` - `agent: Agent{ agent_name}` @@ -126962,208 +139659,190 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` - - The unique ID of the tool search call generated by the model. - - - `execution: :server | :client` - - Whether tool search was executed by the server or by the client. - - - `:server` - - - `:client` - - - `status: :in_progress | :completed | :incomplete` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The status of the tool search output. + The execution context that produced this tool call. - - `:in_progress` + - `class Direct` - - `:completed` + - `type: :direct` - - `:incomplete` + - `:direct` - - `class AdditionalTools` + - `class Program` - - `role: :developer` + - `caller_id: String` - The role that provided the additional tools. Only `developer` is supported. + The call ID of the program item that produced this tool call. - - `:developer` + - `type: :program` - - `tools: Array[BetaTool]` + - `:program` - A list of additional tools made available at this item. + - `created_by: String` - - `class BetaFunctionTool` + The ID of the entity that created 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). + - `class BetaResponseApplyPatchToolCallOutput` - - `class BetaFileSearchTool` + The output emitted by an apply patch 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). + - `id: String` - - `class BetaComputerTool` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `call_id: String` - - `class BetaComputerUsePreviewTool` + The unique ID of the apply patch tool call generated by the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `status: :completed | :failed` - - `class BetaWebSearchTool` + The status of the apply patch tool call output. One of `completed` or `failed`. - 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). + - `:completed` - - `class Mcp` + - `:failed` - 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: :apply_patch_call_output` - - `class CodeInterpreter` + The type of the item. Always `apply_patch_call_output`. - A tool that runs Python code to help generate a response to a prompt. + - `:apply_patch_call_output` - - `class ProgrammaticToolCalling` + - `agent: Agent{ agent_name}` - - `class ImageGeneration` + The agent that produced this item. - A tool that generates images using the GPT image models. + - `agent_name: String` - - `class LocalShell` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `class BetaFunctionShellTool` + The execution context that produced this tool call. - A tool that allows the model to execute shell commands. + - `class Direct` - - `class BetaCustomTool` + - `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) + - `:direct` - - `class BetaNamespaceTool` + - `class Program` - Groups function/custom tools under a shared namespace. + - `caller_id: String` - - `class BetaToolSearchTool` + The call ID of the program item that produced this tool call. - Hosted or BYOT tool search configuration for deferred tools. + - `type: :program` - - `class BetaWebSearchPreviewTool` + - `: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: String` - - `class BetaApplyPatchTool` + The ID of the entity that created this tool call output. - Allows the assistant to create, delete, or update files using unified diffs. + - `output: String` - - `type: :additional_tools` + Optional textual output returned by the apply patch tool. - The item type. Always `additional_tools`. + - `class McpCall` - - `:additional_tools` + An invocation of a tool on an MCP server. - `id: String` - The unique ID of this additional tools item. + The unique ID of the tool call. - - `agent: Agent{ agent_name}` + - `arguments: String` - The agent that produced this item. + A JSON string of the arguments passed to the tool. - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the tool that was run. - - `class BetaResponseReasoningItem` + - `server_label: 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). + The label of the MCP server running the tool. - - `id: String` + - `type: :mcp_call` - The unique identifier of the reasoning content. + The type of the item. Always `mcp_call`. - - `summary: Array[Summary{ text, type}]` + - `:mcp_call` - Reasoning summary content. + - `agent: Agent{ agent_name}` - - `text: String` + The agent that produced this item. - A summary of the reasoning output from the model so far. + - `agent_name: String` - - `type: :summary_text` + The canonical name of the agent that produced this item. - The type of the object. Always `summary_text`. + - `approval_request_id: String` - - `:summary_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. - - `type: :reasoning` + - `error: String` - The type of the object. Always `reasoning`. + The error from the tool call, if any. - - `:reasoning` + - `output: String` - - `agent: Agent{ agent_name}` + The output from the tool call. - The agent that produced this item. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `agent_name: String` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The canonical name of the agent that produced this item. + - `:in_progress` - - `content: Array[Content{ text, type}]` + - `:completed` - Reasoning text content. + - `:incomplete` - - `text: String` + - `:calling` - The reasoning text from the model. + - `:failed` - - `type: :reasoning_text` + - `class McpListTools` - The type of the reasoning text. Always `reasoning_text`. + A list of tools available on an MCP server. - - `:reasoning_text` + - `id: String` - - `encrypted_content: String` + The unique ID of the list. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `server_label: String` - - `status: :in_progress | :completed | :incomplete` + The label of the MCP server. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - - `:in_progress` + The tools available on the server. - - `:completed` + - `input_schema: untyped` - - `:incomplete` + The JSON schema describing the tool's input. - - `class BetaResponseCompactionItemParam` + - `name: String` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The name of the tool. - - `encrypted_content: String` + - `annotations: untyped` - The encrypted content of the compaction summary. + Additional annotations about the tool. - - `type: :compaction` + - `description: String` - The type of the item. Always `compaction`. + The description of the tool. - - `:compaction` + - `type: :mcp_list_tools` - - `id: String` + The type of the item. Always `mcp_list_tools`. - The ID of the compaction item. + - `:mcp_list_tools` - `agent: Agent{ agent_name}` @@ -127173,35 +139852,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ImageGenerationCall` + - `error: String` - An image generation request made by the model. + Error message if the server could not list tools. - - `id: String` + - `class McpApprovalRequest` - The unique ID of the image generation call. + A request for human approval of a tool invocation. - - `result: String` + - `id: String` - The generated image encoded in base64. + The unique ID of the approval request. - - `status: :in_progress | :completed | :generating | :failed` + - `arguments: String` - The status of the image generation call. + A JSON string of arguments for the tool. - - `:in_progress` + - `name: String` - - `:completed` + The name of the tool to run. - - `:generating` + - `server_label: String` - - `:failed` + The label of the MCP server making the request. - - `type: :image_generation_call` + - `type: :mcp_approval_request` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `mcp_approval_request`. - - `:image_generation_call` + - `:mcp_approval_request` - `agent: Agent{ agent_name}` @@ -127211,58 +139890,56 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall` + - `class McpApprovalResponse` - A tool call to run code. + A response to an MCP approval request. - `id: String` - The unique ID of the code interpreter tool call. - - - `code: String` + The unique ID of the approval response - The code to run, or null if not available. + - `approval_request_id: String` - - `container_id: String` + The ID of the approval request being answered. - The ID of the container used to run the code. + - `approve: bool` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + Whether the request was approved. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `type: :mcp_approval_response` - - `class Logs` + The type of the item. Always `mcp_approval_response`. - The logs output from the code interpreter. + - `:mcp_approval_response` - - `logs: String` + - `agent: Agent{ agent_name}` - The logs output from the code interpreter. + The agent that produced this item. - - `type: :logs` + - `agent_name: String` - The type of the output. Always `logs`. + The canonical name of the agent that produced this item. - - `:logs` + - `reason: String` - - `class Image` + Optional reason for the decision. - The image output from the code interpreter. + - `class BetaResponseCustomToolCall` - - `type: :image` + A call to a custom tool created by the model. - The type of the output. Always `image`. + - `class BetaResponseCustomToolCallOutputItem` - - `:image` + The output of a custom tool call from your code, being sent back to the model. - - `url: String` + - `id: String` - The URL of the image output from the code interpreter. + The unique ID of the custom tool call output item. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `status: :in_progress | :completed | :incomplete` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `:in_progress` @@ -127270,5343 +139947,5426 @@ puts(beta_compacted_response) - `:incomplete` - - `:interpreting` + - `created_by: String` - - `:failed` + The identifier of the actor that created the item. - - `type: :code_interpreter_call` + - `parallel_tool_calls: bool` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Whether to allow the model to run tool calls in parallel. - - `:code_interpreter_call` + - `temperature: Float` - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - - `agent_name: String` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The canonical name of the agent that produced this item. + - `BetaToolChoiceOptions = :none | :auto | :required` - - `class LocalShellCall` + Controls which (if any) tool is called by the model. - A tool call to run a command on the local shell. + `none` means the model will not call any tool and instead generates a message. - - `id: String` + `auto` means the model can pick between generating a message or calling one or + more tools. - The unique ID of the local shell call. + `required` means the model must call one or more tools. - - `action: Action{ command, env, type, 3 more}` + - `:none` - Execute a shell command on the server. + - `:auto` - - `command: Array[String]` + - `:required` - The command to run. + - `class BetaToolChoiceAllowed` - - `env: Hash[Symbol, String]` + Constrains the tools available to the model to a pre-defined set. - Environment variables to set for the command. + - `mode: :auto | :required` - - `type: :exec` + Constrains the tools available to the model to a pre-defined set. - The type of the local shell action. Always `exec`. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `:exec` + `required` requires the model to call one or more of the allowed tools. - - `timeout_ms: Integer` + - `:auto` - Optional timeout in milliseconds for the command. + - `:required` - - `user: String` + - `tools: Array[Hash[Symbol, untyped]]` - Optional user to run the command as. + A list of tool definitions that the model should be allowed to call. - - `working_directory: String` + For the Responses API, the list of tool definitions might look like: - Optional working directory to run the command in. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `call_id: String` + - `type: :allowed_tools` - The unique ID of the local shell tool call generated by the model. + Allowed tool configuration type. Always `allowed_tools`. - - `status: :in_progress | :completed | :incomplete` + - `:allowed_tools` - The status of the local shell call. + - `class BetaToolChoiceTypes` - - `:in_progress` + 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). - - `:completed` + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `:incomplete` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `type: :local_shell_call` + Allowed values are: - The type of the local shell call. Always `local_shell_call`. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `:local_shell_call` + - `:file_search` - - `agent: Agent{ agent_name}` + - `:web_search_preview` - The agent that produced this item. + - `:computer` - - `agent_name: String` + - `:computer_use_preview` - The canonical name of the agent that produced this item. + - `:computer_use` - - `class LocalShellCallOutput` + - `:web_search_preview_2025_03_11` - The output of a local shell tool call. + - `:image_generation` - - `id: String` + - `:code_interpreter` - The unique ID of the local shell tool call generated by the model. + - `class BetaToolChoiceFunction` - - `output: String` + Use this option to force the model to call a specific function. - A JSON string of the output of the local shell tool call. + - `name: String` - - `type: :local_shell_call_output` + The name of the function to call. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `type: :function` - - `:local_shell_call_output` + For function calling, the type is always `function`. - - `agent: Agent{ agent_name}` + - `:function` - The agent that produced this item. + - `class BetaToolChoiceMcp` - - `agent_name: String` + Use this option to force the model to call a specific tool on a remote MCP server. - The canonical name of the agent that produced this item. + - `server_label: String` - - `status: :in_progress | :completed | :incomplete` + The label of the MCP server to use. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `type: :mcp` - - `:in_progress` + For MCP tools, the type is always `mcp`. - - `:completed` + - `:mcp` - - `:incomplete` + - `name: String` - - `class ShellCall` + The name of the tool to call on the server. - A tool representing a request to execute one or more shell commands. + - `class BetaToolChoiceCustom` - - `action: Action{ 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[String]` + The name of the custom tool to call. - Ordered shell commands for the execution environment to run. + - `type: :custom` - - `max_output_length: Integer` + 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: Integer` + - `class BetaSpecificProgrammaticToolCallingParam` - 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` + - `class BetaToolChoiceApplyPatch` - 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: 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: Agent{ agent_name}` + - `class BetaToolChoiceShell` - 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_: Direct{ type} | Program{ caller_id, type}` + - `:shell` - The execution context that produced this tool call. + - `tools: Array[BetaTool]` - - `class Direct` + 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](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` + - `class BetaFunctionTool` - - `class 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). - - `caller_id: String` + - `class BetaFileSearchTool` - The call ID of the program item that produced this 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). - - `type: :program` + - `class BetaComputerTool` - The caller type. Always `program`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `:program` + - `class BetaComputerUsePreviewTool` - - `environment: BetaLocalEnvironment | BetaContainerReference` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The environment to execute the shell commands in. + - `class BetaWebSearchTool` - - `class BetaLocalEnvironment` + 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). - - `class BetaContainerReference` + - `class Mcp` - - `status: :in_progress | :completed | :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 shell call. One of `in_progress`, `completed`, or `incomplete`. + - `class CodeInterpreter` - - `:in_progress` + A tool that runs Python code to help generate a response to a prompt. - - `:completed` + - `class ProgrammaticToolCalling` - - `:incomplete` + - `class ImageGeneration` - - `class ShellCallOutput` + A tool that generates images using the GPT image models. - The streamed output items emitted by a shell tool call. + - `class LocalShell` - - `call_id: String` + A tool that allows the model to execute shell commands in a local environment. - The unique ID of the shell tool call generated by the model. + - `class BetaFunctionShellTool` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + A tool that allows the model to execute shell commands. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `class BetaCustomTool` - - `outcome: Timeout{ type} | Exit{ exit_code, 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) - The exit or timeout outcome associated with this shell call. + - `class BetaNamespaceTool` - - `class Timeout` + Groups function/custom tools under a shared namespace. - Indicates that the shell call exceeded its configured time limit. + - `class BetaToolSearchTool` - - `type: :timeout` + Hosted or BYOT tool search configuration for deferred tools. - The outcome type. Always `timeout`. + - `class BetaWebSearchPreviewTool` - - `:timeout` + 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). - - `class Exit` + - `class BetaApplyPatchTool` - Indicates that the shell commands finished and returned an exit code. + Allows the assistant to create, delete, or update files using unified diffs. - - `exit_code: Integer` + - `top_p: Float` - The exit code returned by the shell process. + 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: :exit` + We generally recommend altering this or `temperature` but not both. - The outcome type. Always `exit`. + - `background: bool` - - `:exit` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `stderr: String` + - `completed_at: Float` - Captured stderr output for the shell call. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `stdout: String` + - `conversation: Conversation{ id}` - Captured stdout output for the shell call. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `type: :shell_call_output` + - `id: String` - The type of the item. Always `shell_call_output`. + The unique ID of the conversation that this response was associated with. - - `:shell_call_output` + - `max_output_tokens: Integer` - - `id: 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 unique ID of the shell tool call output. Populated when this item is returned via API. + - `max_tool_calls: Integer` - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `moderation: Moderation{ input, output}` - - `agent_name: String` + Moderation results for the response input and output, if moderated completions were requested. - The canonical name of the agent that produced this item. + - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Moderation for the response input. - The execution context that produced this tool call. + - `class ModerationResult` - - `class Direct` + A moderation result produced for the response input or output. - - `type: :direct` + - `categories: Hash[Symbol, bool]` - The caller type. Always `direct`. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:direct` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `class Program` + Which modalities of input are reflected by the score for each category. - - `caller_id: String` + - `:text` - The call ID of the program item that produced this tool call. + - `:image` - - `type: :program` + - `category_scores: Hash[Symbol, Float]` - The caller type. Always `program`. + A dictionary of moderation categories to scores. - - `:program` + - `flagged: bool` - - `max_output_length: Integer` + A boolean indicating whether the content was flagged by any category. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `model: String` - - `status: :in_progress | :completed | :incomplete` + The moderation model that produced this result. - The status of the shell call output. + - `type: :moderation_result` - - `:in_progress` + The object type, which was always `moderation_result` for successful moderation results. - - `:completed` + - `:moderation_result` - - `:incomplete` + - `class Error` - - `class ApplyPatchCall` + An error produced while attempting moderation for the response input or output. - A tool call representing a request to create, delete, or update files using diff patches. + - `code: String` - - `call_id: String` + The error code. - The unique ID of the apply patch tool call generated by the model. + - `message: String` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + The error message. - The specific create, delete, or update instruction for the apply_patch tool call. + - `type: :error` - - `class CreateFile` + The object type, which was always `error` for moderation failures. - Instruction for creating a new file via the apply_patch tool. + - `:error` - - `diff: String` + - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` - Unified diff content to apply when creating the file. + Moderation for the response output. - - `path: String` + - `class ModerationResult` - Path of the file to create relative to the workspace root. + A moderation result produced for the response input or output. - - `type: :create_file` + - `categories: Hash[Symbol, bool]` - The operation type. Always `create_file`. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `:create_file` + - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` - - `class DeleteFile` + Which modalities of input are reflected by the score for each category. - Instruction for deleting an existing file via the apply_patch tool. + - `:text` - - `path: String` + - `:image` - Path of the file to delete relative to the workspace root. + - `category_scores: Hash[Symbol, Float]` - - `type: :delete_file` + A dictionary of moderation categories to scores. - The operation type. Always `delete_file`. + - `flagged: bool` - - `:delete_file` + A boolean indicating whether the content was flagged by any category. - - `class UpdateFile` + - `model: String` - Instruction for updating an existing file via the apply_patch tool. + The moderation model that produced this result. - - `diff: String` + - `type: :moderation_result` - Unified diff content to apply to the existing file. + The object type, which was always `moderation_result` for successful moderation results. - - `path: String` + - `:moderation_result` - Path of the file to update relative to the workspace root. + - `class Error` - - `type: :update_file` + An error produced while attempting moderation for the response input or output. - The operation type. Always `update_file`. + - `code: String` - - `:update_file` + The error code. - - `status: :in_progress | :completed` + - `message: String` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The error message. - - `:in_progress` + - `type: :error` - - `:completed` + The object type, which was always `error` for moderation failures. - - `type: :apply_patch_call` + - `:error` - The type of the item. Always `apply_patch_call`. + - `previous_response_id: String` - - `:apply_patch_call` + 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`. - - `id: String` + - `prompt: BetaResponsePrompt` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `agent: Agent{ agent_name}` + - `id: String` - The agent that produced this item. + The unique identifier of the prompt template to use. - - `agent_name: String` + - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - The canonical name of 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. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `String = String` - The execution context that produced this tool call. + - `class BetaResponseInputText` - - `class Direct` + A text input to the model. - - `type: :direct` + - `class BetaResponseInputImage` - The caller type. Always `direct`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:direct` + - `class BetaResponseInputFile` - - `class Program` + A file input to the model. - - `caller_id: String` + - `version: String` - The call ID of the program item that produced this tool call. + Optional version of the prompt template. - - `type: :program` + - `prompt_cache_key: String` - The caller type. Always `program`. + 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). - - `:program` + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` - - `class ApplyPatchCallOutput` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The streamed output emitted by an apply patch tool call. + - `mode: :implicit | :explicit` - - `call_id: String` + Whether implicit prompt-cache breakpoints were enabled. - The unique ID of the apply patch tool call generated by the model. + - `:implicit` - - `status: :completed | :failed` + - `:explicit` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `ttl: :"30m"` - - `:completed` + The minimum lifetime applied to each cache breakpoint. - - `:failed` + - `:"30m"` - - `type: :apply_patch_call_output` + - `prompt_cache_retention: :in_memory | :"24h"` - The type of the item. Always `apply_patch_call_output`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `:apply_patch_call_output` + 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. - - `id: String` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `agent: Agent{ agent_name}` + - `:in_memory` - The agent that produced this item. + - `:"24h"` - - `agent_name: String` + - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - The canonical name of the agent that produced this item. + **gpt-5 and o-series models only** - - `caller_: Direct{ type} | Program{ caller_id, type}` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The execution context that produced this tool call. + - `context: :auto | :current_turn | :all_turns` - - `class Direct` + 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: :direct` + - `:auto` - The caller type. Always `direct`. + - `:current_turn` - - `:direct` + - `:all_turns` - - `class Program` + - `effort: :none | :minimal | :low | 4 more` - - `caller_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 call ID of the program item that produced this tool call. + - `:none` - - `type: :program` + - `:minimal` - The caller type. Always `program`. + - `:low` - - `:program` + - `:medium` - - `output: String` + - `:high` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `:xhigh` - - `class McpListTools` + - `:max` - A list of tools available on an MCP server. + - `generate_summary: :auto | :concise | :detailed` - - `id: String` + **Deprecated:** use `summary` instead. - The unique ID of the list. + 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`. - - `server_label: String` + - `:auto` - The label of the MCP server. + - `:concise` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `:detailed` - The tools available on the server. + - `mode: String | :standard | :pro` - - `input_schema: untyped` + Controls the reasoning execution mode for the request. - The JSON schema describing the tool's input. + When returned on a response, this is the effective execution mode. - - `name: String` + - `String = String` - The name of the tool. + - `Mode = :standard | :pro` - - `annotations: untyped` + Controls the reasoning execution mode for the request. - Additional annotations about the tool. + When returned on a response, this is the effective execution mode. - - `description: String` + - `:standard` - The description of the tool. + - `:pro` - - `type: :mcp_list_tools` + - `summary: :auto | :concise | :detailed` - The type of the item. Always `mcp_list_tools`. + 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`. - - `:mcp_list_tools` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `agent: Agent{ agent_name}` + - `:auto` - The agent that produced this item. + - `:concise` - - `agent_name: String` + - `:detailed` - The canonical name of the agent that produced this item. + - `safety_identifier: String` - - `error: 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). - Error message if the server could not list tools. + - `service_tier: :auto | :default | :flex | 2 more` - - `class McpApprovalRequest` + Specifies the processing type used for serving the request. - A request for human approval of a tool invocation. + - 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'. - - `id: 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 unique ID of the approval request. + - `:auto` - - `arguments: String` + - `:default` - A JSON string of arguments for the tool. + - `:flex` - - `name: String` + - `:scale` - The name of the tool to run. + - `:priority` - - `server_label: String` + - `status: BetaResponseStatus` - The label of the MCP server making the request. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `type: :mcp_approval_request` + - `:completed` - The type of the item. Always `mcp_approval_request`. + - `:failed` - - `:mcp_approval_request` + - `:in_progress` - - `agent: Agent{ agent_name}` + - `:cancelled` - The agent that produced this item. + - `:queued` - - `agent_name: String` + - `:incomplete` - The canonical name of the agent that produced this item. + - `text: BetaResponseTextConfig` - - `class McpApprovalResponse` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A response to an MCP approval request. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `approval_request_id: String` + - `format_: BetaResponseFormatTextConfig` - The ID of the approval request being answered. + An object specifying the format that the model must output. - - `approve: bool` + 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). - Whether the request was approved. + The default format is `{ "type": "text" }` with no additional options. - - `type: :mcp_approval_response` + **Not recommended for gpt-4o and newer models:** - The type of the item. Always `mcp_approval_response`. + 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. - - `:mcp_approval_response` + - `class Text` - - `id: String` + Default response format. Used to generate text responses. - The unique ID of the approval response + - `type: :text` - - `agent: Agent{ agent_name}` + The type of response format being defined. Always `text`. - The agent that produced this item. + - `:text` - - `agent_name: String` + - `class BetaResponseFormatTextJSONSchemaConfig` - The canonical name of 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). - - `reason: String` + - `name: String` - Optional reason for the decision. + 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. - - `class McpCall` + - `schema: Hash[Symbol, untyped]` - An invocation of a tool on an MCP server. + 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 tool call. + The type of response format being defined. Always `json_schema`. - - `arguments: String` + - `:json_schema` - A JSON string of the arguments passed to the tool. + - `description: String` - - `name: String` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The name of the tool that was run. + - `strict: bool` - - `server_label: 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 label of the MCP server running the tool. + - `class JSONObject` - - `type: :mcp_call` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The type of the item. Always `mcp_call`. + - `type: :json_object` - - `:mcp_call` + The type of response format being defined. Always `json_object`. - - `agent: Agent{ agent_name}` + - `:json_object` - The agent that produced this item. + - `verbosity: :low | :medium | :high` - - `agent_name: 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 canonical name of the agent that produced this item. + - `:low` - - `approval_request_id: String` + - `:medium` - 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: String` + - `top_logprobs: Integer` - The error from the tool call, if any. + 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. - - `output: String` + - `truncation: :auto | :disabled` - The output from the tool call. + The truncation strategy to use for the model response. - - `status: :in_progress | :completed | :incomplete | 2 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. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `:auto` - - `:in_progress` + - `:disabled` - - `:completed` + - `usage: BetaResponseUsage` - - `:incomplete` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `:calling` + - `input_tokens: Integer` - - `:failed` + The number of input tokens. - - `class BetaResponseCustomToolCallOutput` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` - The output of a custom tool call from your code, being sent back to the model. + A detailed breakdown of the input tokens. - - `call_id: String` + - `cache_write_tokens: Integer` - The call ID, used to map this custom tool call output to a custom tool call. + The number of input tokens that were written to the cache. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `cached_tokens: Integer` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `String = String` + - `output_tokens: Integer` - A string of the output of the custom tool call. + The number of output tokens. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` - Text, image, or file output of the custom tool call. + A detailed breakdown of the output tokens. - - `class BetaResponseInputText` + - `reasoning_tokens: Integer` - A text input to the model. + The number of reasoning tokens. - - `class BetaResponseInputImage` + - `total_tokens: Integer` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The total number of tokens used. - - `class BetaResponseInputFile` + - `user: String` - A file input to the model. + 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: :custom_tool_call_output` + - `sequence_number: Integer` - The type of the custom tool call output. Always `custom_tool_call_output`. + The sequence number for this event. - - `:custom_tool_call_output` + - `type: :"response.completed"` - - `id: String` + The type of the event. Always `response.completed`. - The unique ID of the custom tool call output in the OpenAI platform. + - `:"response.completed"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseContentPartAddedEvent` - The execution context that produced this tool call. + Emitted when a new content part is added. - - `class Direct` + - `content_index: Integer` - - `type: :direct` + The index of the content part that was added. - The caller type. Always `direct`. + - `item_id: String` - - `:direct` + The ID of the output item that the content part was added to. - - `class Program` + - `output_index: Integer` - - `caller_id: String` + The index of the output item that the content part was added to. - The call ID of the program item that produced this tool call. + - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` - - `type: :program` + The content part that was added. - The caller type. Always `program`. + - `class BetaResponseOutputText` - - `:program` + A text output from the model. - - `class BetaResponseCustomToolCall` + - `class BetaResponseOutputRefusal` - A call to a custom tool created by the model. + A refusal from the model. - - `call_id: String` + - `class ReasoningText` - An identifier used to map this custom tool call to a tool call output. + Reasoning text from the model. - - `input: String` + - `text: String` - The input for the custom tool call generated by the model. + The reasoning text from the model. - - `name: String` + - `type: :reasoning_text` - The name of the custom tool being called. + The type of the reasoning text. Always `reasoning_text`. - - `type: :custom_tool_call` + - `:reasoning_text` - The type of the custom tool call. Always `custom_tool_call`. + - `sequence_number: Integer` - - `:custom_tool_call` + The sequence number of this event. - - `id: String` + - `type: :"response.content_part.added"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the event. Always `response.content_part.added`. + + - `:"response.content_part.added"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseContentPartDoneEvent` - The execution context that produced this tool call. + Emitted when a content part is done. - - `class Direct` + - `content_index: Integer` - - `type: :direct` + The index of the content part that is done. - - `:direct` + - `item_id: String` - - `class Program` + The ID of the output item that the content part was added to. - - `caller_id: String` + - `output_index: Integer` - The call ID of the program item that produced this tool call. + The index of the output item that the content part was added to. - - `type: :program` + - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` - - `:program` + The content part that is done. - - `namespace: String` + - `class BetaResponseOutputText` - The namespace of the custom tool being called. + A text output from the model. - - `class CompactionTrigger` + - `class BetaResponseOutputRefusal` - Compacts the current context. Must be the final input item. + A refusal from the model. - - `type: :compaction_trigger` + - `class ReasoningText` - The type of the item. Always `compaction_trigger`. + Reasoning text from the model. - - `:compaction_trigger` + - `text: String` - - `agent: Agent{ 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` - - `class ItemReference` + - `sequence_number: Integer` - An internal identifier for an item to reference. + The sequence number of this event. - - `id: String` + - `type: :"response.content_part.done"` - The ID of the item to reference. + The type of the event. Always `response.content_part.done`. + + - `:"response.content_part.done"` - `agent: Agent{ agent_name}` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: String` The canonical name of the agent that produced this item. - - `type: :item_reference` - - The type of item to reference. Always `item_reference`. - - - `:item_reference` - - - `class Program` - - - `id: String` - - The unique ID of this program item. - - - `call_id: String` + - `class BetaResponseCreatedEvent` - The stable call ID of the program item. + An event that is emitted when a response is created. - - `code: String` + - `response: BetaResponse` - The JavaScript source executed by programmatic tool calling. + The response that was created. - - `fingerprint: String` + - `sequence_number: Integer` - Opaque program replay fingerprint that must be round-tripped. + The sequence number for this event. - - `type: :program` + - `type: :"response.created"` - The item type. Always `program`. + The type of the event. Always `response.created`. - - `:program` + - `:"response.created"` - `agent: Agent{ 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. - - `class ProgramOutput` - - - `id: String` + - `class BetaResponseErrorEvent` - The unique ID of this program output item. + Emitted when an error occurs. - - `call_id: String` + - `code: String` - The call ID of the program item. + The error code. - - `result: String` + - `message: String` - The result produced by the program item. + The error message. - - `status: :completed | :incomplete` + - `param: String` - The terminal status of the program output. + The error parameter. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of this event. - - `type: :program_output` + - `type: :error` - The item type. Always `program_output`. + The type of the event. Always `error`. - - `:program_output` + - `:error` - `agent: Agent{ 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. - - `metadata: Hash[Symbol, 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" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | 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. - - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `class BetaResponseFileSearchCallCompletedEvent` - 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. + Emitted when a file search call is completed (results found). - - `:"gpt-5.6-sol"` + - `item_id: String` - - `:"gpt-5.6-terra"` + The ID of the output item that the file search call is initiated. - - `:"gpt-5.6-luna"` + - `output_index: Integer` - - `:"gpt-5.4"` + The index of the output item that the file search call is initiated. - - `:"gpt-5.4-mini"` + - `sequence_number: Integer` - - `:"gpt-5.4-nano"` + The sequence number of this event. - - `:"gpt-5.4-mini-2026-03-17"` + - `type: :"response.file_search_call.completed"` - - `:"gpt-5.4-nano-2026-03-17"` + The type of the event. Always `response.file_search_call.completed`. - - `:"gpt-5.3-chat-latest"` + - `:"response.file_search_call.completed"` - - `:"gpt-5.2"` + - `agent: Agent{ agent_name}` - - `:"gpt-5.2-2025-12-11"` + The agent that owns this multi-agent streaming event. - - `:"gpt-5.2-chat-latest"` + - `agent_name: String` - - `:"gpt-5.2-pro"` + The canonical name of the agent that produced this item. - - `:"gpt-5.2-pro-2025-12-11"` + - `class BetaResponseFileSearchCallInProgressEvent` - - `:"gpt-5.1"` + Emitted when a file search call is initiated. - - `:"gpt-5.1-2025-11-13"` + - `item_id: String` - - `:"gpt-5.1-codex"` + The ID of the output item that the file search call is initiated. - - `:"gpt-5.1-mini"` + - `output_index: Integer` - - `:"gpt-5.1-chat-latest"` + The index of the output item that the file search call is initiated. - - `:"gpt-5"` + - `sequence_number: Integer` - - `:"gpt-5-mini"` + The sequence number of this event. - - `:"gpt-5-nano"` + - `type: :"response.file_search_call.in_progress"` - - `:"gpt-5-2025-08-07"` + The type of the event. Always `response.file_search_call.in_progress`. - - `:"gpt-5-mini-2025-08-07"` + - `:"response.file_search_call.in_progress"` - - `:"gpt-5-nano-2025-08-07"` + - `agent: Agent{ agent_name}` - - `:"gpt-5-chat-latest"` + The agent that owns this multi-agent streaming event. - - `:"gpt-4.1"` + - `agent_name: String` - - `:"gpt-4.1-mini"` + The canonical name of the agent that produced this item. - - `:"gpt-4.1-nano"` + - `class BetaResponseFileSearchCallSearchingEvent` - - `:"gpt-4.1-2025-04-14"` + Emitted when a file search is currently searching. - - `:"gpt-4.1-mini-2025-04-14"` + - `item_id: String` - - `:"gpt-4.1-nano-2025-04-14"` + The ID of the output item that the file search call is initiated. - - `:"o4-mini"` + - `output_index: Integer` - - `:"o4-mini-2025-04-16"` + The index of the output item that the file search call is searching. - - `:o3` + - `sequence_number: Integer` - - `:"o3-2025-04-16"` + The sequence number of this event. - - `:"o3-mini"` + - `type: :"response.file_search_call.searching"` - - `:"o3-mini-2025-01-31"` + The type of the event. Always `response.file_search_call.searching`. - - `:o1` + - `:"response.file_search_call.searching"` - - `:"o1-2024-12-17"` + - `agent: Agent{ agent_name}` - - `:"o1-preview"` + The agent that owns this multi-agent streaming event. - - `:"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"` + - `class BetaResponseFunctionCallArgumentsDeltaEvent` - - `:"gpt-4o"` + Emitted when there is a partial function-call arguments delta. - - `:"gpt-4o-2024-11-20"` + - `delta: String` - - `:"gpt-4o-2024-08-06"` + The function-call arguments delta that is added. - - `:"gpt-4o-2024-05-13"` + - `item_id: String` - - `:"gpt-4o-audio-preview"` + The ID of the output item that the function-call arguments delta is added to. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `output_index: Integer` - - `:"gpt-4o-audio-preview-2024-12-17"` + The index of the output item that the function-call arguments delta is added to. - - `:"gpt-4o-audio-preview-2025-06-03"` + - `sequence_number: Integer` - - `:"gpt-4o-mini-audio-preview"` + The sequence number of this event. - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: :"response.function_call_arguments.delta"` - - `:"gpt-4o-search-preview"` + The type of the event. Always `response.function_call_arguments.delta`. - - `:"gpt-4o-mini-search-preview"` + - `:"response.function_call_arguments.delta"` - - `:"gpt-4o-search-preview-2025-03-11"` + - `agent: Agent{ agent_name}` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + The agent that owns this multi-agent streaming event. - - `:"chatgpt-4o-latest"` + - `agent_name: String` - - `:"codex-mini-latest"` + The canonical name of the agent that produced this item. - - `:"gpt-4o-mini"` + - `class BetaResponseFunctionCallArgumentsDoneEvent` - - `:"gpt-4o-mini-2024-07-18"` + Emitted when function-call arguments are finalized. - - `:"gpt-4-turbo"` + - `arguments: String` - - `:"gpt-4-turbo-2024-04-09"` + The function-call arguments. - - `:"gpt-4-0125-preview"` + - `item_id: String` - - `:"gpt-4-turbo-preview"` + The ID of the item. - - `:"gpt-4-1106-preview"` + - `name: String` - - `:"gpt-4-vision-preview"` + The name of the function that was called. - - `:"gpt-4"` + - `output_index: Integer` - - `:"gpt-4-0314"` + The index of the output item. - - `:"gpt-4-0613"` + - `sequence_number: Integer` - - `:"gpt-4-32k"` + The sequence number of this event. - - `:"gpt-4-32k-0314"` + - `type: :"response.function_call_arguments.done"` - - `:"gpt-4-32k-0613"` + - `:"response.function_call_arguments.done"` - - `:"gpt-3.5-turbo"` + - `agent: Agent{ agent_name}` - - `:"gpt-3.5-turbo-16k"` + The agent that owns this multi-agent streaming event. - - `:"gpt-3.5-turbo-0301"` + - `agent_name: String` - - `:"gpt-3.5-turbo-0613"` + The canonical name of the agent that produced this item. - - `:"gpt-3.5-turbo-1106"` + - `class BetaResponseInProgressEvent` - - `:"gpt-3.5-turbo-0125"` + Emitted when the response is in progress. - - `:"gpt-3.5-turbo-16k-0613"` + - `response: BetaResponse` - - `:"o1-pro"` + The response that is in progress. - - `:"o1-pro-2025-03-19"` + - `sequence_number: Integer` - - `:"o3-pro"` + The sequence number of this event. - - `:"o3-pro-2025-06-10"` + - `type: :"response.in_progress"` - - `:"o3-deep-research"` + The type of the event. Always `response.in_progress`. - - `:"o3-deep-research-2025-06-26"` + - `:"response.in_progress"` - - `:"o4-mini-deep-research"` + - `agent: Agent{ 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"` + - `class BetaResponseFailedEvent` - - `:"gpt-5-pro"` + An event that is emitted when a response fails. - - `:"gpt-5-pro-2025-10-06"` + - `response: BetaResponse` - - `:"gpt-5.1-codex-max"` + The response that failed. - - `String = String` + - `sequence_number: Integer` - - `object: :response` + The sequence number of this event. - The object type of this resource - always set to `response`. + - `type: :"response.failed"` - - `:response` + The type of the event. Always `response.failed`. - - `output: Array[BetaResponseOutputItem]` + - `:"response.failed"` - An array of content items generated by the model. + - `agent: Agent{ 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. - - `class BetaResponseOutputMessage` + - `agent_name: String` - An output message from the model. + The canonical name of the agent that produced this item. - - `class BetaResponseFileSearchToolCall` + - `class BetaResponseIncompleteEvent` - 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. + An event that is emitted when a response finishes as incomplete. - - `class BetaResponseFunctionToolCall` + - `response: BetaResponse` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The response that was incomplete. - - `class BetaResponseFunctionToolCallOutputItem` + - `sequence_number: Integer` - - `id: String` + The sequence number of this event. - The unique ID of the function call tool output. + - `type: :"response.incomplete"` - - `call_id: String` + The type of the event. Always `response.incomplete`. - The unique ID of the function tool call generated by the model. + - `:"response.incomplete"` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `agent: Agent{ agent_name}` - The output from the function call generated by your code. - Can be a string or an list of output content. + The agent that owns this multi-agent streaming event. - - `String = String` + - `agent_name: String` - A string of the output of the function call. + The canonical name of the agent that produced this item. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class BetaResponseOutputItemAddedEvent` - Text, image, or file output of the function call. + Emitted when a new output item is added. - - `class BetaResponseInputText` + - `item: BetaResponseOutputItem` - A text input to the model. + The output item that was added. - - `class BetaResponseInputImage` + - `class BetaResponseOutputMessage` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An output message from the model. - - `class BetaResponseInputFile` + - `class BetaResponseFileSearchToolCall` - A file input to the model. + 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. - - `status: :in_progress | :completed | :incomplete` + - `class BetaResponseFunctionToolCall` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:in_progress` + - `class BetaResponseFunctionToolCallOutputItem` - - `:completed` + - `class AgentMessage` - - `:incomplete` + - `class MultiAgentCall` - - `type: :function_call_output` + - `class MultiAgentCallOutput` - The type of the function tool call output. Always `function_call_output`. + - `class BetaResponseFunctionWebSearch` - - `:function_call_output` + 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. - - `agent: Agent{ agent_name}` + - `class BetaResponseComputerToolCall` - The agent that produced this item. + 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. - - `agent_name: String` + - `class BetaResponseComputerToolCallOutputItem` - The canonical name of the agent that produced this item. + - `class BetaResponseReasoningItem` - - `caller_: Direct{ type} | Program{ caller_id, type}` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The execution context that produced this tool call. + - `class Program` - - `class Direct` + - `class ProgramOutput` - - `type: :direct` + - `class BetaResponseToolSearchCall` - The caller type. Always `direct`. + - `class BetaResponseToolSearchOutputItem` - - `:direct` + - `class AdditionalTools` - - `class Program` + - `class BetaResponseCompactionItem` - - `caller_id: String` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The call ID of the program item that produced this tool call. + - `class ImageGenerationCall` - - `type: :program` + An image generation request made by the model. - The caller type. Always `program`. + - `class BetaResponseCodeInterpreterToolCall` - - `:program` + A tool call to run code. - - `created_by: String` + - `class LocalShellCall` - The identifier of the actor that created the item. + A tool call to run a command on the local shell. - - `class AgentMessage` + - `class LocalShellCallOutput` - - `id: String` + The output of a local shell tool call. - The unique ID of the agent message. + - `class BetaResponseFunctionShellToolCall` - - `author: String` + A tool call that executes one or more shell commands in a managed environment. - The sending agent identity. + - `class BetaResponseFunctionShellToolCallOutput` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + The output of a shell tool call that was emitted. - Encrypted content sent between agents. + - `class BetaResponseApplyPatchToolCall` - - `class BetaResponseInputText` + A tool call that applies file diffs by creating, deleting, or updating files. - A text input to the model. + - `class BetaResponseApplyPatchToolCallOutput` - - `class BetaResponseOutputText` + The output emitted by an apply patch tool call. - A text output from the model. + - `class McpCall` - - `class Text` + An invocation of a tool on an MCP server. - A text content. + - `class McpListTools` - - `text: String` + A list of tools available on an MCP server. - - `type: :text` + - `class McpApprovalRequest` - - `:text` + A request for human approval of a tool invocation. - - `class SummaryText` + - `class McpApprovalResponse` - A summary text from the model. + A response to an MCP approval request. - - `text: String` + - `class BetaResponseCustomToolCall` - A summary of the reasoning output from the model so far. + A call to a custom tool created by the model. - - `type: :summary_text` + - `class BetaResponseCustomToolCallOutputItem` - The type of the object. Always `summary_text`. + The output of a custom tool call from your code, being sent back to the model. - - `:summary_text` + - `output_index: Integer` - - `class ReasoningText` + The index of the output item that was added. - Reasoning text from the model. + - `sequence_number: Integer` - - `text: String` + The sequence number of this event. - The reasoning text from the model. + - `type: :"response.output_item.added"` - - `type: :reasoning_text` + The type of the event. Always `response.output_item.added`. - The type of the reasoning text. Always `reasoning_text`. + - `:"response.output_item.added"` - - `:reasoning_text` + - `agent: Agent{ agent_name}` - - `class BetaResponseOutputRefusal` + The agent that owns this multi-agent streaming event. - A refusal from the model. + - `agent_name: String` - - `class BetaResponseInputImage` + 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). + - `class BetaResponseOutputItemDoneEvent` - - `class ComputerScreenshot` + Emitted when an output item is marked done. - A screenshot of a computer. + - `item: BetaResponseOutputItem` - - `detail: :low | :high | :auto | :original` + The output item that was marked done. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `output_index: Integer` - - `:low` + The index of the output item that was marked done. - - `:high` + - `sequence_number: Integer` - - `:auto` + The sequence number of this event. - - `:original` + - `type: :"response.output_item.done"` - - `file_id: String` + The type of the event. Always `response.output_item.done`. - The identifier of an uploaded file that contains the screenshot. + - `:"response.output_item.done"` - - `image_url: String` + - `agent: Agent{ agent_name}` - The URL of the screenshot image. + The agent that owns this multi-agent streaming event. - - `type: :computer_screenshot` + - `agent_name: String` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The canonical name of the agent that produced this item. - - `:computer_screenshot` + - `class BetaResponseReasoningSummaryPartAddedEvent` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Emitted when a new reasoning summary part is added. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `item_id: String` - - `mode: :explicit` + The ID of the item this summary part is associated with. - The breakpoint mode. Always `explicit`. + - `output_index: Integer` - - `:explicit` + The index of the output item this summary part is associated with. - - `class BetaResponseInputFile` + - `part: Part{ text, type}` - A file input to the model. + The summary part that was added. - - `class EncryptedContent` + - `text: String` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The text of the summary part. - - `encrypted_content: String` + - `type: :summary_text` - Opaque encrypted content. + The type of the summary part. Always `summary_text`. - - `type: :encrypted_content` + - `:summary_text` - The type of the input item. Always `encrypted_content`. + - `sequence_number: Integer` - - `:encrypted_content` + The sequence number of this event. - - `recipient: String` + - `summary_index: Integer` - The destination agent identity. + The index of the summary part within the reasoning summary. - - `type: :agent_message` + - `type: :"response.reasoning_summary_part.added"` - The type of the item. Always `agent_message`. + The type of the event. Always `response.reasoning_summary_part.added`. - - `:agent_message` + - `:"response.reasoning_summary_part.added"` - `agent: Agent{ 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. - - `class MultiAgentCall` + - `class BetaResponseReasoningSummaryPartDoneEvent` - - `id: String` + Emitted when a reasoning summary part is completed. - The unique ID of the multi-agent call item. + - `item_id: String` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The ID of the item this summary part is associated with. - The multi-agent action to execute. + - `output_index: Integer` - - `:spawn_agent` + The index of the output item this summary part is associated with. - - `:interrupt_agent` + - `part: Part{ text, type}` - - `:list_agents` + The completed summary part. - - `:send_message` + - `text: String` - - `:followup_task` + The text of the summary part. - - `:wait_agent` + - `type: :summary_text` - - `arguments: String` + The type of the summary part. Always `summary_text`. - The JSON string of arguments generated for the action. + - `:summary_text` - - `call_id: String` + - `sequence_number: Integer` - The unique ID linking this call to its output. + The sequence number of this event. - - `type: :multi_agent_call` + - `summary_index: Integer` - The type of the multi-agent call. Always `multi_agent_call`. + The index of the summary part within the reasoning summary. - - `:multi_agent_call` + - `type: :"response.reasoning_summary_part.done"` + + The type of the event. Always `response.reasoning_summary_part.done`. + + - `:"response.reasoning_summary_part.done"` - `agent: Agent{ 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. - - `class MultiAgentCallOutput` - - - `id: String` + - `status: :incomplete` - The unique ID of the multi-agent call output item. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:incomplete` - The multi-agent action that produced this result. + - `class BetaResponseReasoningSummaryTextDeltaEvent` - - `:spawn_agent` + Emitted when a delta is added to a reasoning summary text. - - `:interrupt_agent` + - `delta: String` - - `:list_agents` + The text delta that was added to the summary. - - `:send_message` + - `item_id: String` - - `:followup_task` + The ID of the item this summary text delta is associated with. - - `:wait_agent` + - `output_index: Integer` - - `call_id: String` + The index of the output item this summary text delta is associated with. - The unique ID of the multi-agent call. + - `sequence_number: Integer` - - `output: Array[BetaResponseOutputText]` + The sequence number of this event. - Text output returned by the multi-agent action. + - `summary_index: Integer` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + The index of the summary part within the reasoning summary. - The annotations of the text output. + - `type: :"response.reasoning_summary_text.delta"` - - `text: String` + The type of the event. Always `response.reasoning_summary_text.delta`. - The text output from the model. + - `:"response.reasoning_summary_text.delta"` - - `type: :output_text` + - `agent: Agent{ agent_name}` - The type of the output text. Always `output_text`. + The agent that owns this multi-agent streaming event. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `agent_name: String` - - `type: :multi_agent_call_output` + The canonical name of the agent that produced this item. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `class BetaResponseReasoningSummaryTextDoneEvent` - - `:multi_agent_call_output` + Emitted when a reasoning summary text is completed. - - `agent: Agent{ agent_name}` + - `item_id: String` - The agent that produced this item. + The ID of the item this summary text is associated with. - - `agent_name: String` + - `output_index: Integer` - The canonical name of the agent that produced this item. + The index of the output item this summary text is associated with. - - `class BetaResponseFunctionWebSearch` + - `sequence_number: Integer` - 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 sequence number of this event. - - `class BetaResponseComputerToolCall` + - `summary_index: Integer` - 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 index of the summary part within the reasoning summary. - - `class BetaResponseComputerToolCallOutputItem` + - `text: String` - - `id: String` + The full text of the completed reasoning summary. - The unique ID of the computer call tool output. + - `type: :"response.reasoning_summary_text.done"` - - `call_id: String` + The type of the event. Always `response.reasoning_summary_text.done`. - The ID of the computer tool call that produced the output. + - `:"response.reasoning_summary_text.done"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `agent: Agent{ agent_name}` - A computer screenshot image used with the computer use tool. + The agent that owns this multi-agent streaming event. - - `status: :completed | :incomplete | :failed | :in_progress` + - `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. - - `:completed` + - `class BetaResponseReasoningTextDeltaEvent` - - `:incomplete` + Emitted when a delta is added to a reasoning text. - - `:failed` + - `content_index: Integer` - - `:in_progress` + The index of the reasoning content part this delta is associated with. - - `type: :computer_call_output` + - `delta: String` - The type of the computer tool call output. Always `computer_call_output`. + The text delta that was added to the reasoning content. - - `:computer_call_output` + - `item_id: String` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + The ID of the item this reasoning text delta is associated with. - The safety checks reported by the API that have been acknowledged by the - developer. + - `output_index: Integer` - - `id: String` + The index of the output item this reasoning text delta is associated with. - The ID of the pending safety check. + - `sequence_number: Integer` - - `code: String` + The sequence number of this event. - The type of the pending safety check. + - `type: :"response.reasoning_text.delta"` - - `message: String` + The type of the event. Always `response.reasoning_text.delta`. - Details about the pending safety check. + - `:"response.reasoning_text.delta"` - `agent: Agent{ 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: String` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningTextDoneEvent` - - `class BetaResponseReasoningItem` + Emitted when a reasoning text is completed. - 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). + - `content_index: Integer` - - `class Program` + The index of the reasoning content part. - - `id: String` + - `item_id: String` - The unique ID of the program item. + The ID of the item this reasoning text is associated with. - - `call_id: String` + - `output_index: Integer` - The stable call ID of the program item. + The index of the output item this reasoning text is associated with. - - `code: String` + - `sequence_number: Integer` - The JavaScript source executed by programmatic tool calling. + The sequence number of this event. - - `fingerprint: String` + - `text: String` - Opaque program replay fingerprint that must be round-tripped. + The full text of the completed reasoning content. - - `type: :program` + - `type: :"response.reasoning_text.done"` - The type of the item. Always `program`. + The type of the event. Always `response.reasoning_text.done`. - - `:program` + - `:"response.reasoning_text.done"` - `agent: Agent{ 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. - - `class ProgramOutput` + - `class BetaResponseRefusalDeltaEvent` - - `id: String` + Emitted when there is a partial refusal text. - The unique ID of the program output item. + - `content_index: Integer` - - `call_id: String` + The index of the content part that the refusal text is added to. - The call ID of the program item. + - `delta: String` - - `result: String` + The refusal text that is added. - The result produced by the program item. + - `item_id: String` - - `status: :completed | :incomplete` + The ID of the output item that the refusal text is added to. - The terminal status of the program output item. + - `output_index: Integer` - - `:completed` + The index of the output item that the refusal text is added to. - - `:incomplete` + - `sequence_number: Integer` - - `type: :program_output` + The sequence number of this event. - The type of the item. Always `program_output`. + - `type: :"response.refusal.delta"` - - `:program_output` + The type of the event. Always `response.refusal.delta`. + + - `:"response.refusal.delta"` - `agent: Agent{ 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. - - `class BetaResponseToolSearchCall` - - - `id: String` - - The unique ID of the tool search call item. - - - `arguments: untyped` - - Arguments used for the tool search call. + - `class BetaResponseRefusalDoneEvent` - - `call_id: String` + Emitted when refusal text is finalized. - The unique ID of the tool search call generated by the model. + - `content_index: Integer` - - `execution: :server | :client` + The index of the content part that the refusal text is finalized. - Whether tool search was executed by the server or by the client. + - `item_id: String` - - `:server` + The ID of the output item that the refusal text is finalized. - - `:client` + - `output_index: Integer` - - `status: :in_progress | :completed | :incomplete` + The index of the output item that the refusal text is finalized. - The status of the tool search call item that was recorded. + - `refusal: String` - - `:in_progress` + The refusal text that is finalized. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of this event. - - `type: :tool_search_call` + - `type: :"response.refusal.done"` - The type of the item. Always `tool_search_call`. + The type of the event. Always `response.refusal.done`. - - `:tool_search_call` + - `:"response.refusal.done"` - `agent: Agent{ 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: String` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem` - - - `id: String` - - The unique ID of the tool search output item. + - `class BetaResponseTextDeltaEvent` - - `call_id: String` + Emitted when there is an additional text delta. - The unique ID of the tool search call generated by the model. + - `content_index: Integer` - - `execution: :server | :client` + The index of the content part that the text delta was added to. - Whether tool search was executed by the server or by the client. + - `delta: String` - - `:server` + The text delta that was added. - - `:client` + - `item_id: String` - - `status: :in_progress | :completed | :incomplete` + The ID of the output item that the text delta was added to. - The status of the tool search output item that was recorded. + - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` - - `:in_progress` + The log probabilities of the tokens in the delta. - - `:completed` + - `token: String` - - `:incomplete` + A possible text token. - - `tools: Array[BetaTool]` + - `logprob: Float` - The loaded tool definitions returned by tool search. + The log probability of this token. - - `class BetaFunctionTool` + - `top_logprobs: Array[TopLogprob{ token, logprob}]` - 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 log probabilities of up to 20 of the most likely tokens. - - `class BetaFileSearchTool` + - `token: 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 possible text token. - - `class BetaComputerTool` + - `logprob: Float` - 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. - - `class BetaComputerUsePreviewTool` + - `output_index: Integer` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the output item that the text delta was added to. - - `class BetaWebSearchTool` + - `sequence_number: Integer` - 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 sequence number for this event. - - `class Mcp` + - `type: :"response.output_text.delta"` - 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 type of the event. Always `response.output_text.delta`. - - `class CodeInterpreter` + - `:"response.output_text.delta"` - A tool that runs Python code to help generate a response to a prompt. + - `agent: Agent{ agent_name}` - - `class ProgrammaticToolCalling` + The agent that owns this multi-agent streaming event. - - `class ImageGeneration` + - `agent_name: String` - A tool that generates images using the GPT image models. + The canonical name of the agent that produced this item. - - `class LocalShell` + - `class BetaResponseTextDoneEvent` - A tool that allows the model to execute shell commands in a local environment. + Emitted when text content is finalized. - - `class BetaFunctionShellTool` + - `content_index: Integer` - A tool that allows the model to execute shell commands. + The index of the content part that the text content is finalized. - - `class BetaCustomTool` + - `item_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 output item that the text content is finalized. - - `class BetaNamespaceTool` + - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` - Groups function/custom tools under a shared namespace. + The log probabilities of the tokens in the delta. - - `class BetaToolSearchTool` + - `token: String` - Hosted or BYOT tool search configuration for deferred tools. + A possible text token. - - `class BetaWebSearchPreviewTool` + - `logprob: Float` - 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 log probability of this token. - - `class BetaApplyPatchTool` + - `top_logprobs: Array[TopLogprob{ 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: :tool_search_output` + - `token: String` - The type of the item. Always `tool_search_output`. + A possible text token. - - `:tool_search_output` + - `logprob: Float` - - `agent: Agent{ agent_name}` + The log probability of this token. - The agent that produced this item. + - `output_index: Integer` - - `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: Integer` - - `created_by: String` + The sequence number for this event. - The identifier of the actor that created the item. + - `text: String` - - `class AdditionalTools` + The text content that is finalized. - - `id: String` + - `type: :"response.output_text.done"` - The unique ID of the additional tools item. + The type of the event. Always `response.output_text.done`. - - `role: :unknown | :user | :assistant | 5 more` + - `:"response.output_text.done"` - The role that provided the additional tools. + - `agent: Agent{ agent_name}` - - `:unknown` + The agent that owns this multi-agent streaming event. - - `:user` + - `agent_name: String` - - `:assistant` + The canonical name of the agent that produced this item. - - `:system` + - `class BetaResponseWebSearchCallCompletedEvent` - - `:critic` + Emitted when a web search call is completed. - - `:discriminator` + - `item_id: String` - - `:developer` + Unique ID for the output item associated with the web search call. - - `:tool` + - `output_index: Integer` - - `tools: Array[BetaTool]` + The index of the output item that the web search call is associated with. - The additional tool definitions made available at this item. + - `sequence_number: Integer` - - `class BetaFunctionTool` + The sequence number of the web search call being processed. - 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: :"response.web_search_call.completed"` - - `class BetaFileSearchTool` + The type of the event. Always `response.web_search_call.completed`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `:"response.web_search_call.completed"` - - `class BetaComputerTool` + - `agent: Agent{ 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. - - `class BetaComputerUsePreviewTool` + - `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. - - `class BetaWebSearchTool` + - `class BetaResponseWebSearchCallInProgressEvent` - 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). + Emitted when a web search call is initiated. - - `class Mcp` + - `item_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). + Unique ID for the output item associated with the web search call. - - `class CodeInterpreter` + - `output_index: Integer` - A tool that runs Python code to help generate a response to a prompt. + The index of the output item that the web search call is associated with. - - `class ProgrammaticToolCalling` + - `sequence_number: Integer` - - `class ImageGeneration` + The sequence number of the web search call being processed. - A tool that generates images using the GPT image models. + - `type: :"response.web_search_call.in_progress"` - - `class LocalShell` + The type of the event. Always `response.web_search_call.in_progress`. - A tool that allows the model to execute shell commands in a local environment. + - `:"response.web_search_call.in_progress"` - - `class BetaFunctionShellTool` + - `agent: Agent{ agent_name}` - A tool that allows the model to execute shell commands. + The agent that owns this multi-agent streaming event. - - `class BetaCustomTool` + - `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. - - `class BetaNamespaceTool` + - `class BetaResponseWebSearchCallSearchingEvent` - Groups function/custom tools under a shared namespace. + Emitted when a web search call is executing. - - `class BetaToolSearchTool` + - `item_id: String` - Hosted or BYOT tool search configuration for deferred tools. + Unique ID for the output item associated with the web search call. - - `class BetaWebSearchPreviewTool` + - `output_index: Integer` - 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 web search call is associated with. - - `class BetaApplyPatchTool` + - `sequence_number: Integer` - Allows the assistant to create, delete, or update files using unified diffs. + The sequence number of the web search call being processed. - - `type: :additional_tools` + - `type: :"response.web_search_call.searching"` - The type of the item. Always `additional_tools`. + The type of the event. Always `response.web_search_call.searching`. - - `:additional_tools` + - `:"response.web_search_call.searching"` - `agent: Agent{ 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. - - `class BetaResponseCompactionItem` + - `class BetaResponseImageGenCallCompletedEvent` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Emitted when an image generation tool call has completed and the final image is available. - - `id: String` + - `item_id: String` - The unique ID of the compaction item. + The unique identifier of the image generation item being processed. - - `encrypted_content: String` + - `output_index: Integer` - The encrypted content that was produced by compaction. + The index of the output item in the response's output array. - - `type: :compaction` + - `sequence_number: Integer` - The type of the item. Always `compaction`. + The sequence number of this event. - - `:compaction` + - `type: :"response.image_generation_call.completed"` + + The type of the event. Always 'response.image_generation_call.completed'. + + - `:"response.image_generation_call.completed"` - `agent: Agent{ 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: String` - - The identifier of the actor that created the item. - - - `class ImageGenerationCall` - - An image generation request made by the model. - - - `id: String` - - The unique ID of the image generation call. - - - `result: String` + - `class BetaResponseImageGenCallGeneratingEvent` - The generated image encoded in base64. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `status: :in_progress | :completed | :generating | :failed` + - `item_id: String` - The status of the image generation call. + The unique identifier of the image generation item being processed. - - `:in_progress` + - `output_index: Integer` - - `:completed` + The index of the output item in the response's output array. - - `:generating` + - `sequence_number: Integer` - - `:failed` + The sequence number of the image generation item being processed. - - `type: :image_generation_call` + - `type: :"response.image_generation_call.generating"` - The type of the image generation call. Always `image_generation_call`. + The type of the event. Always 'response.image_generation_call.generating'. - - `:image_generation_call` + - `:"response.image_generation_call.generating"` - `agent: Agent{ 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. - - `class BetaResponseCodeInterpreterToolCall` - - A tool call to run code. + - `class BetaResponseImageGenCallInProgressEvent` - - `class LocalShellCall` + Emitted when an image generation tool 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 image generation item being processed. - The unique ID of the local shell call. + - `output_index: Integer` - - `action: Action{ command, env, type, 3 more}` + The index of the output item in the response's output array. - Execute a shell command on the server. + - `sequence_number: Integer` - - `command: Array[String]` + The sequence number of the image generation item being processed. - The command to run. + - `type: :"response.image_generation_call.in_progress"` - - `env: Hash[Symbol, String]` + The type of the event. Always 'response.image_generation_call.in_progress'. - Environment variables to set for the command. + - `:"response.image_generation_call.in_progress"` - - `type: :exec` + - `agent: Agent{ 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: Integer` + The canonical name of the agent that produced this item. - Optional timeout in milliseconds for the command. + - `class BetaResponseImageGenCallPartialImageEvent` - - `user: String` + Emitted when a partial image is available during image generation streaming. - Optional user to run the command as. + - `item_id: String` - - `working_directory: String` + The unique identifier of the image generation item being processed. - Optional working directory to run the command in. + - `output_index: Integer` - - `call_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. + - `partial_image_b64: String` - - `status: :in_progress | :completed | :incomplete` + Base64-encoded partial image data, suitable for rendering as an image. - The status of the local shell call. + - `partial_image_index: Integer` - - `:in_progress` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of the image generation item being processed. - - `type: :local_shell_call` + - `type: :"response.image_generation_call.partial_image"` - The type of the local shell call. Always `local_shell_call`. + The type of the event. Always 'response.image_generation_call.partial_image'. - - `:local_shell_call` + - `:"response.image_generation_call.partial_image"` - `agent: Agent{ 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. - - `class LocalShellCallOutput` - - The output of a local shell tool call. + - `class BetaResponseMcpCallArgumentsDeltaEvent` - - `id: String` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - The unique ID of the local shell tool call generated by the model. + - `delta: String` - - `output: String` + A JSON string containing the partial update to the arguments for the MCP tool call. - A JSON string of the output of the local shell tool call. + - `item_id: String` - - `type: :local_shell_call_output` + The unique identifier of the MCP tool call item being processed. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `output_index: Integer` - - `:local_shell_call_output` + The index of the output item in the response's output array. - - `agent: Agent{ agent_name}` + - `sequence_number: Integer` - The agent that produced this item. + The sequence number of this event. - - `agent_name: String` + - `type: :"response.mcp_call_arguments.delta"` - The canonical name of the agent that produced this item. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `status: :in_progress | :completed | :incomplete` + - `:"response.mcp_call_arguments.delta"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `agent: Agent{ 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. - - `class BetaResponseFunctionShellToolCall` + - `class BetaResponseMcpCallArgumentsDoneEvent` - A tool call that executes one or more shell commands in a managed environment. + Emitted when the arguments for an MCP tool call are finalized. - - `id: String` + - `arguments: String` - The unique ID of the shell tool call. Populated when this item is returned via API. + A JSON string containing the finalized arguments for the MCP tool call. - - `action: Action{ commands, max_output_length, timeout_ms}` + - `item_id: String` - The shell commands and limits that describe how to run the tool call. + The unique identifier of the MCP tool call item being processed. - - `commands: Array[String]` + - `output_index: Integer` - - `max_output_length: Integer` + The index of the output item in the response's output array. - Optional maximum number of characters to return from each command. + - `sequence_number: Integer` - - `timeout_ms: Integer` + The sequence number of this event. - Optional timeout in milliseconds for the commands. + - `type: :"response.mcp_call_arguments.done"` - - `call_id: String` + The type of the event. Always 'response.mcp_call_arguments.done'. - The unique ID of the shell tool call generated by the model. + - `:"response.mcp_call_arguments.done"` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `agent: Agent{ agent_name}` - Represents the use of a local environment to perform shell actions. + The agent that owns this multi-agent streaming event. - - `class BetaResponseLocalEnvironment` + - `agent_name: String` - Represents the use of a local environment to perform shell actions. + The canonical name of the agent that produced this item. - - `type: :local` + - `class BetaResponseMcpCallCompletedEvent` - The environment type. Always `local`. + Emitted when an MCP tool call has completed successfully. - - `:local` + - `item_id: String` - - `class BetaResponseContainerReference` + The ID of the MCP tool call item that completed. - Represents a container created with /v1/containers. + - `output_index: Integer` - - `container_id: String` + The index of the output item that completed. - - `type: :container_reference` + - `sequence_number: Integer` - The environment type. Always `container_reference`. + The sequence number of this event. - - `:container_reference` + - `type: :"response.mcp_call.completed"` - - `status: :in_progress | :completed | :incomplete` + The type of the event. Always 'response.mcp_call.completed'. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `:"response.mcp_call.completed"` - - `:in_progress` + - `agent: Agent{ agent_name}` - - `:completed` + The agent that owns this multi-agent streaming event. - - `:incomplete` + - `agent_name: String` - - `type: :shell_call` + The canonical name of the agent that produced this item. - The type of the item. Always `shell_call`. + - `class BetaResponseMcpCallFailedEvent` - - `:shell_call` + Emitted when an MCP tool call has failed. - - `agent: Agent{ agent_name}` + - `item_id: String` - The agent that produced this item. + The ID of the MCP tool call item that failed. - - `agent_name: String` + - `output_index: Integer` - The canonical name of the agent that produced this item. + The index of the output item that failed. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `sequence_number: Integer` - The execution context that produced this tool call. + The sequence number of this event. - - `class Direct` + - `type: :"response.mcp_call.failed"` - - `type: :direct` + The type of the event. Always 'response.mcp_call.failed'. - - `:direct` + - `:"response.mcp_call.failed"` - - `class Program` + - `agent: Agent{ agent_name}` - - `caller_id: String` + The agent that owns this multi-agent streaming event. - The call ID of the program item that produced this tool call. + - `agent_name: String` - - `type: :program` + The canonical name of the agent that produced this item. - - `:program` + - `class BetaResponseMcpCallInProgressEvent` - - `created_by: String` + Emitted when an MCP tool call is in progress. - The ID of the entity that created this tool call. + - `item_id: String` - - `class BetaResponseFunctionShellToolCallOutput` + The unique identifier of the MCP tool call item being processed. - The output of a shell tool call that was emitted. + - `output_index: Integer` - - `id: String` + The index of the output item in the response's output array. - The unique ID of the shell call output. Populated when this item is returned via API. + - `sequence_number: Integer` - - `call_id: String` + The sequence number of this event. - The unique ID of the shell tool call generated by the model. + - `type: :"response.mcp_call.in_progress"` - - `max_output_length: Integer` + The type of the event. Always 'response.mcp_call.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. + - `:"response.mcp_call.in_progress"` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `agent: Agent{ agent_name}` - An array of shell call output contents + The agent that owns this multi-agent streaming event. - - `outcome: Timeout{ type} | Exit{ 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. - - `class Timeout` + - `class BetaResponseMcpListToolsCompletedEvent` - Indicates that the shell call exceeded its configured time limit. + Emitted when the list of available MCP tools has been successfully retrieved. - - `type: :timeout` + - `item_id: String` - The outcome type. Always `timeout`. + The ID of the MCP tool call item that produced this output. - - `:timeout` + - `output_index: Integer` - - `class Exit` + The index of the output item that was processed. - Indicates that the shell commands finished and returned an exit code. + - `sequence_number: Integer` - - `exit_code: Integer` + The sequence number of this event. - Exit code from the shell process. + - `type: :"response.mcp_list_tools.completed"` - - `type: :exit` + The type of the event. Always 'response.mcp_list_tools.completed'. - The outcome type. Always `exit`. + - `:"response.mcp_list_tools.completed"` - - `:exit` + - `agent: Agent{ agent_name}` - - `stderr: String` + The agent that owns this multi-agent streaming event. - The standard error output that was captured. + - `agent_name: String` - - `stdout: String` + The canonical name of the agent that produced this item. - The standard output that was captured. + - `class BetaResponseMcpListToolsFailedEvent` - - `created_by: String` + Emitted when the attempt to list available MCP tools has failed. - The identifier of the actor that created the item. + - `item_id: String` - - `status: :in_progress | :completed | :incomplete` + The ID of the MCP tool call item that failed. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `output_index: Integer` - - `:in_progress` + The index of the output item that failed. - - `:completed` + - `sequence_number: Integer` - - `:incomplete` + The sequence number of this event. - - `type: :shell_call_output` + - `type: :"response.mcp_list_tools.failed"` - The type of the shell call output. Always `shell_call_output`. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `:shell_call_output` + - `:"response.mcp_list_tools.failed"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` + - `class BetaResponseMcpListToolsInProgressEvent` - - `type: :direct` + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `:direct` + - `item_id: String` - - `class Program` + The ID of the MCP tool call item that is being processed. - - `caller_id: String` + - `output_index: Integer` - The call ID of the program item that produced this tool call. + The index of the output item that is being processed. - - `type: :program` + - `sequence_number: Integer` - - `:program` + The sequence number of this event. - - `created_by: String` + - `type: :"response.mcp_list_tools.in_progress"` - The identifier of the actor that created the item. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `class BetaResponseApplyPatchToolCall` + - `:"response.mcp_list_tools.in_progress"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `agent: Agent{ agent_name}` - - `id: String` + The agent that owns this multi-agent streaming event. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent_name: String` - - `call_id: String` + The canonical name of the agent that produced this item. - The unique ID of the apply patch tool call generated by the model. + - `class BetaResponseOutputTextAnnotationAddedEvent` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + Emitted when an annotation is added to output text content. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `annotation: untyped` - - `class CreateFile` + The annotation object being added. (See annotation schema for details.) - Instruction describing how to create a file via the apply_patch tool. + - `annotation_index: Integer` - - `diff: String` + The index of the annotation within the content part. - Diff to apply. + - `content_index: Integer` - - `path: String` + The index of the content part within the output item. - Path of the file to create. + - `item_id: String` - - `type: :create_file` + The unique identifier of the item to which the annotation is being added. - Create a new file with the provided diff. + - `output_index: Integer` - - `:create_file` + The index of the output item in the response's output array. - - `class DeleteFile` + - `sequence_number: Integer` - Instruction describing how to delete a file via the apply_patch tool. + The sequence number of this event. - - `path: String` + - `type: :"response.output_text.annotation.added"` - Path of the file to delete. + The type of the event. Always 'response.output_text.annotation.added'. - - `type: :delete_file` + - `:"response.output_text.annotation.added"` - Delete the specified file. + - `agent: Agent{ agent_name}` - - `:delete_file` + The agent that owns this multi-agent streaming event. - - `class UpdateFile` + - `agent_name: String` - Instruction describing how to update a file via the apply_patch tool. + The canonical name of the agent that produced this item. - - `diff: String` + - `class BetaResponseQueuedEvent` - Diff to apply. + Emitted when a response is queued and waiting to be processed. - - `path: String` + - `response: BetaResponse` - Path of the file to update. + The full response object that is queued. - - `type: :update_file` + - `sequence_number: Integer` - Update an existing file with the provided diff. + The sequence number for this event. - - `:update_file` + - `type: :"response.queued"` - - `status: :in_progress | :completed` + The type of the event. Always 'response.queued'. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:"response.queued"` - - `:in_progress` + - `agent: Agent{ agent_name}` - - `:completed` + The agent that owns this multi-agent streaming event. - - `type: :apply_patch_call` + - `agent_name: String` - The type of the item. Always `apply_patch_call`. + The canonical name of the agent that produced this item. - - `:apply_patch_call` + - `class BetaResponseCustomToolCallInputDeltaEvent` - - `agent: Agent{ agent_name}` + Event representing a delta (partial update) to the input of a custom tool call. - The agent that produced this item. + - `delta: String` - - `agent_name: String` + The incremental input data (delta) for the custom tool call. - The canonical name of the agent that produced this item. + - `item_id: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Unique identifier for the API item associated with this event. - The execution context that produced this tool call. + - `output_index: Integer` - - `class Direct` + The index of the output this delta applies to. - - `type: :direct` + - `sequence_number: Integer` - - `:direct` + The sequence number of this event. - - `class Program` + - `type: :"response.custom_tool_call_input.delta"` - - `caller_id: String` + The event type identifier. - The call ID of the program item that produced this tool call. + - `:"response.custom_tool_call_input.delta"` - - `type: :program` + - `agent: Agent{ agent_name}` - - `:program` + The agent that owns this multi-agent streaming event. - - `created_by: String` + - `agent_name: String` - The ID of the entity that created this tool call. + The canonical name of the agent that produced this item. - - `class BetaResponseApplyPatchToolCallOutput` + - `class BetaResponseCustomToolCallInputDoneEvent` - The output emitted by an apply patch tool call. + Event indicating that input for a custom tool call is complete. - - `id: String` + - `input: String` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The complete input data for the custom tool call. - - `call_id: String` + - `item_id: String` - The unique ID of the apply patch tool call generated by the model. + Unique identifier for the API item associated with this event. - - `status: :completed | :failed` + - `output_index: Integer` - The status of the apply patch tool call output. One of `completed` or `failed`. + The index of the output this event applies to. - - `:completed` + - `sequence_number: Integer` - - `:failed` + The sequence number of this event. - - `type: :apply_patch_call_output` + - `type: :"response.custom_tool_call_input.done"` - The type of the item. Always `apply_patch_call_output`. + The event type identifier. - - `:apply_patch_call_output` + - `:"response.custom_tool_call_input.done"` - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseInjectCreatedEvent` - The execution context that produced this tool call. + Emitted when all injected input items were validated and committed to the + active response. - - `class Direct` + - `response_id: String` - - `type: :direct` + The ID of the response that accepted the input. - - `:direct` + - `sequence_number: Integer` - - `class Program` + The sequence number for this event. - - `caller_id: String` + - `type: :"response.inject.created"` - The call ID of the program item that produced this tool call. + The event discriminator. Always `response.inject.created`. - - `type: :program` + - `:"response.inject.created"` - - `:program` + - `stream_id: String` - - `created_by: String` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The ID of the entity that created this tool call output. + - `class BetaResponseInjectFailedEvent` - - `output: String` + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - Optional textual output returned by the apply patch tool. + - `error: Error{ code, message}` - - `class McpCall` + Information about why the input was not committed. - An invocation of a tool on an MCP server. + - `code: :response_already_completed | :response_not_found` - - `id: String` + A machine-readable error code. - The unique ID of the tool call. + - `:response_already_completed` - - `arguments: String` + - `:response_not_found` - A JSON string of the arguments passed to the tool. + - `message: String` - - `name: String` + A human-readable description of the error. - The name of the tool that was run. + - `input: Array[BetaResponseInputItem]` - - `server_label: String` + The raw input items that were not committed. - The label of the MCP server running the tool. + - `class BetaEasyInputMessage` - - `type: :mcp_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. - The type of the item. Always `mcp_call`. + - `class Message` - - `:mcp_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. - - `agent: Agent{ agent_name}` + - `class BetaResponseOutputMessage` - The agent that produced this item. + An output message from the model. - - `agent_name: String` + - `class BetaResponseFileSearchToolCall` - The canonical name of the agent that produced this item. + 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. - - `approval_request_id: String` + - `class BetaResponseComputerToolCall` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `error: String` + - `class ComputerCallOutput` - The error from the tool call, if any. + The output of a computer tool call. - - `output: String` + - `class BetaResponseFunctionWebSearch` - The output from the tool call. + 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. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `class BetaResponseFunctionToolCall` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `:in_progress` + - `class FunctionCallOutput` - - `:completed` + The output of a function tool call. - - `:incomplete` + - `class AgentMessage` - - `:calling` + A message routed between agents. - - `:failed` + - `class MultiAgentCall` - - `class McpListTools` + - `class MultiAgentCallOutput` - A list of tools available on an MCP server. + - `class ToolSearchCall` - - `id: String` + - `class BetaResponseToolSearchOutputItemParam` - The unique ID of the list. + - `class AdditionalTools` - - `server_label: String` + - `class BetaResponseReasoningItem` - The label of the MCP 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](https://platform.openai.com/docs/guides/conversation-state). - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `class BetaResponseCompactionItemParam` - The tools available on the server. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `input_schema: untyped` + - `class ImageGenerationCall` - The JSON schema describing the tool's input. + An image generation request made by the model. - - `name: String` + - `class BetaResponseCodeInterpreterToolCall` - The name of the tool. + A tool call to run code. - - `annotations: untyped` + - `class LocalShellCall` - Additional annotations about the tool. + A tool call to run a command on the local shell. - - `description: String` + - `class LocalShellCallOutput` - The description of the tool. + The output of a local shell tool call. - - `type: :mcp_list_tools` + - `class ShellCall` - The type of the item. Always `mcp_list_tools`. + A tool representing a request to execute one or more shell commands. - - `:mcp_list_tools` + - `class ShellCallOutput` - - `agent: Agent{ agent_name}` + The streamed output items emitted by a shell tool call. - The agent that produced this item. + - `class ApplyPatchCall` - - `agent_name: String` + A tool call representing a request to create, delete, or update files using diff patches. - The canonical name of the agent that produced this item. + - `class ApplyPatchCallOutput` - - `error: String` + The streamed output emitted by an apply patch tool call. - Error message if the server could not list tools. + - `class McpListTools` + + A list of tools available on an MCP server. - `class McpApprovalRequest` A request for human approval of a tool invocation. - - `id: String` + - `class McpApprovalResponse` - The unique ID of the approval request. + A response to an MCP approval request. - - `arguments: String` + - `class McpCall` - A JSON string of arguments for the tool. + An invocation of a tool on an MCP server. - - `name: String` + - `class BetaResponseCustomToolCallOutput` - The name of the tool to run. + The output of a custom tool call from your code, being sent back to the model. - - `server_label: String` + - `class BetaResponseCustomToolCall` - The label of the MCP server making the request. + A call to a custom tool created by the model. - - `type: :mcp_approval_request` + - `class CompactionTrigger` - The type of the item. Always `mcp_approval_request`. + Compacts the current context. Must be the final input item. - - `:mcp_approval_request` + - `class ItemReference` - - `agent: Agent{ agent_name}` + An internal identifier for an item to reference. - The agent that produced this item. + - `class Program` - - `agent_name: String` + - `class ProgramOutput` - The canonical name of the agent that produced this item. + - `response_id: String` - - `class McpApprovalResponse` + The ID of the response that rejected the input. - A response to an MCP approval request. + - `sequence_number: Integer` - - `id: String` + The sequence number for this event. - The unique ID of the approval response + - `type: :"response.inject.failed"` - - `approval_request_id: String` + The event discriminator. Always `response.inject.failed`. - The ID of the approval request being answered. + - `:"response.inject.failed"` - - `approve: bool` + - `stream_id: String` - Whether the request was approved. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `type: :mcp_approval_response` +### Beta Skill Reference - The type of the item. Always `mcp_approval_response`. +- `class BetaSkillReference` - - `:mcp_approval_response` + - `skill_id: String` - - `agent: Agent{ agent_name}` + The ID of the referenced skill. - The agent that produced this item. + - `type: :skill_reference` - - `agent_name: String` + References a skill created with the /v1/skills endpoint. - The canonical name of the agent that produced this item. + - `:skill_reference` - - `reason: String` + - `version: String` - Optional reason for the decision. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `class BetaResponseCustomToolCall` +### Beta Tool - A call to a custom tool created by the model. +- `BetaTool = BetaFunctionTool | BetaFileSearchTool | BetaComputerTool | 13 more` - - `class BetaResponseCustomToolCallOutputItem` + A tool that can be used to generate a response. - The output of a custom tool call from your code, being sent back to the model. + - `class BetaFunctionTool` - - `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 custom tool call output item. + - `name: String` - - `status: :in_progress | :completed | :incomplete` + The name of the function to call. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `parameters: Hash[Symbol, untyped]` - - `:in_progress` + A JSON schema object describing the parameters of the function. - - `:completed` + - `strict: bool` - - `:incomplete` + Whether strict parameter validation is enforced for this function tool. - - `created_by: String` + - `type: :function` - The identifier of the actor that created the item. + The type of the function tool. Always `function`. - - `parallel_tool_calls: bool` + - `:function` - Whether to allow the model to run tool calls in parallel. + - `allowed_callers: Array[:direct | :programmatic]` - - `temperature: Float` + The tool invocation context(s). - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `:direct` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `:programmatic` - 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. + - `defer_loading: bool` - - `BetaToolChoiceOptions = :none | :auto | :required` + Whether this function is deferred and loaded via tool search. - Controls which (if any) tool is called by the model. + - `description: String` - `none` means the model will not call any tool and instead generates a message. + A description of the function. Used by the model to determine whether or not to call the function. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `output_schema: Hash[Symbol, untyped]` - `required` means the model must call one or more tools. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `:none` + - `class BetaFileSearchTool` - - `:auto` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `:required` + - `type: :file_search` - - `class BetaToolChoiceAllowed` + The type of the file search tool. Always `file_search`. - Constrains the tools available to the model to a pre-defined set. + - `:file_search` - - `mode: :auto | :required` + - `vector_store_ids: Array[String]` - Constrains the tools available to the model to a pre-defined set. + The IDs of the vector stores to search. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - `required` requires the model to call one or more of the allowed tools. + A filter to apply. - - `:auto` + - `class ComparisonFilter` - - `:required` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `tools: Array[Hash[Symbol, untyped]]` + - `key: String` - A list of tool definitions that the model should be allowed to call. + The key to compare against the value. - For the Responses API, the list of tool definitions might look like: + - `type: :eq | :ne | :gt | 5 more` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: :allowed_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 - Allowed tool configuration type. Always `allowed_tools`. + - `:eq` - - `:allowed_tools` + - `:ne` - - `class BetaToolChoiceTypes` + - `:gt` - 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). + - `:gte` - - `type: :file_search | :web_search_preview | :computer | 5 more` + - `:lt` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `:lte` - Allowed values are: + - `:in` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `:nin` - - `:file_search` + - `value: String | Float | bool | Array[String | Float]` - - `:web_search_preview` + The value to compare against the attribute key; supports string, number, or boolean types. - - `:computer` + - `String = String` - - `:computer_use_preview` + - `Float = Float` - - `:computer_use` + - `UnionMember2 = bool` - - `:web_search_preview_2025_03_11` + - `UnionMember3 = Array[String | Float]` - - `:image_generation` + - `String = String` - - `:code_interpreter` + - `Float = Float` - - `class BetaToolChoiceFunction` + - `class CompoundFilter` - Use this option to force the model to call a specific function. + Combine multiple filters using `and` or `or`. - - `name: String` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - The name of the function to call. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: :function` + - `class ComparisonFilter` - For function calling, the type is always `function`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `:function` + - `key: String` - - `class BetaToolChoiceMcp` + The key to compare against the value. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: :eq | :ne | :gt | 5 more` - - `server_label: String` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The label of the MCP server to use. + - `eq`: equals + - `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: :mcp` + - `:eq` - For MCP tools, the type is always `mcp`. + - `:ne` - - `:mcp` + - `:gt` - - `name: String` + - `:gte` - The name of the tool to call on the server. + - `:lt` - - `class BetaToolChoiceCustom` + - `:lte` - Use this option to force the model to call a specific custom tool. + - `:in` - - `name: String` + - `:nin` - The name of the custom tool to call. + - `value: String | Float | bool | Array[String | Float]` - - `type: :custom` + The value to compare against the attribute key; supports string, number, or boolean types. - For custom tool calling, the type is always `custom`. + - `String = String` - - `:custom` + - `Float = Float` - - `class BetaSpecificProgrammaticToolCallingParam` + - `UnionMember2 = bool` - - `type: :programmatic_tool_calling` + - `UnionMember3 = Array[String | Float]` - The tool to call. Always `programmatic_tool_calling`. + - `String = String` - - `:programmatic_tool_calling` + - `Float = Float` - - `class BetaToolChoiceApplyPatch` + - `UnionMember1 = untyped` - Forces the model to call the apply_patch tool when executing a tool call. + - `type: :and | :or` - - `type: :apply_patch` + Type of operation: `and` or `or`. - The tool to call. Always `apply_patch`. + - `:and` - - `:apply_patch` + - `:or` - - `class BetaToolChoiceShell` + - `max_num_results: Integer` - Forces the model to call the shell tool when a tool call is required. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: :shell` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The tool to call. Always `shell`. + Ranking options for search. - - `:shell` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `tools: Array[BetaTool]` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - 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. + - `embedding_weight: Float` - We support the following categories of tools: + The weight of the embedding in the reciprocal ranking fusion. - - **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. + - `text_weight: Float` - - `class BetaFunctionTool` + The weight of the text in the reciprocal ranking fusion. - 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). + - `ranker: :auto | :"default-2024-11-15"` - - `class BetaFileSearchTool` + The ranker to use for the file search. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `:auto` + + - `:"default-2024-11-15"` + + - `score_threshold: Float` + + 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. - `class BetaComputerTool` 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` + - `class BetaComputerUsePreviewTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaWebSearchTool` + - `display_height: Integer` - 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 height of the computer display. - - `class Mcp` + - `display_width: Integer` - 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 width of the computer display. - - `class CodeInterpreter` + - `environment: :windows | :mac | :linux | 2 more` - A tool that runs Python code to help generate a response to a prompt. + The type of computer environment to control. - - `class ProgrammaticToolCalling` + - `:windows` - - `class ImageGeneration` + - `:mac` - A tool that generates images using the GPT image models. + - `:linux` - - `class LocalShell` + - `:ubuntu` - A tool that allows the model to execute shell commands in a local environment. + - `:browser` - - `class BetaFunctionShellTool` + - `type: :computer_use_preview` - A tool that allows the model to execute shell commands. + The type of the computer use tool. Always `computer_use_preview`. - - `class BetaCustomTool` + - `:computer_use_preview` - 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) + - `class BetaWebSearchTool` - - `class BetaNamespaceTool` + 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). - Groups function/custom tools under a shared namespace. + - `type: :web_search | :web_search_2025_08_26` - - `class BetaToolSearchTool` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Hosted or BYOT tool search configuration for deferred tools. + - `:web_search` - - `class BetaWebSearchPreviewTool` + - `:web_search_2025_08_26` - 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). + - `filters: Filters{ allowed_domains}` - - `class BetaApplyPatchTool` + Filters for the search. - Allows the assistant to create, delete, or update files using unified diffs. + - `allowed_domains: Array[String]` - - `top_p: Float` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - 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. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - We generally recommend altering this or `temperature` but not both. + - `search_context_size: :low | :medium | :high` - - `background: bool` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `:low` - - `completed_at: Float` + - `:medium` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `:high` - - `conversation: Conversation{ id}` + - `user_location: UserLocation{ city, country, region, 2 more}` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The approximate location of the user. - - `id: String` + - `city: String` - The unique ID of the conversation that this response was associated with. + Free text input for the city of the user, e.g. `San Francisco`. - - `max_output_tokens: Integer` + - `country: 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 two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `max_tool_calls: Integer` + - `region: 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. + Free text input for the region of the user, e.g. `California`. - - `moderation: Moderation{ input, output}` + - `timezone: String` - Moderation results for the response input and output, if moderated completions were requested. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + - `type: :approximate` - Moderation for the response input. + The type of location approximation. Always `approximate`. - - `class ModerationResult` + - `:approximate` - A moderation result produced for the response input or output. + - `class Mcp` - - `categories: Hash[Symbol, bool]` + 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 dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `server_label: String` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + A label for this MCP server, used to identify it in tool calls. - Which modalities of input are reflected by the score for each category. + - `type: :mcp` - - `:text` + The type of the MCP tool. Always `mcp`. - - `:image` + - `:mcp` - - `category_scores: Hash[Symbol, Float]` + - `allowed_callers: Array[:direct | :programmatic]` - A dictionary of moderation categories to scores. + The tool invocation context(s). - - `flagged: bool` + - `:direct` - A boolean indicating whether the content was flagged by any category. + - `:programmatic` - - `model: String` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - The moderation model that produced this result. + List of allowed tool names or a filter object. - - `type: :moderation_result` + - `McpAllowedTools = Array[String]` - The object type, which was always `moderation_result` for successful moderation results. + A string array of allowed tool names - - `:moderation_result` + - `class McpToolFilter` - - `class Error` + A filter object to specify which tools are allowed. - An error produced while attempting moderation for the response input or output. + - `read_only: bool` - - `code: 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 error code. + - `tool_names: Array[String]` - - `message: String` + List of allowed tool names. - The error message. + - `authorization: String` - - `type: :error` + 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 object type, which was always `error` for moderation failures. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `:error` + 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). - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + Currently supported `connector_id` values are: - Moderation for the response output. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `class ModerationResult` + - `:connector_dropbox` - A moderation result produced for the response input or output. + - `:connector_gmail` - - `categories: Hash[Symbol, bool]` + - `:connector_googlecalendar` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `:connector_googledrive` - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `:connector_microsoftteams` - Which modalities of input are reflected by the score for each category. + - `:connector_outlookcalendar` - - `:text` + - `:connector_outlookemail` - - `:image` + - `:connector_sharepoint` - - `category_scores: Hash[Symbol, Float]` + - `defer_loading: bool` - A dictionary of moderation categories to scores. + Whether this MCP tool is deferred and discovered via tool search. - - `flagged: bool` + - `headers: Hash[Symbol, String]` - A boolean indicating whether the content was flagged by any category. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `model: String` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - The moderation model that produced this result. + Specify which of the MCP server's tools require approval. - - `type: :moderation_result` + - `class McpToolApprovalFilter` - The object type, which was always `moderation_result` for successful moderation results. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `:moderation_result` + - `always: Always{ read_only, tool_names}` - - `class Error` + A filter object to specify which tools are allowed. - An error produced while attempting moderation for the response input or output. + - `read_only: bool` - - `code: 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 error code. + - `tool_names: Array[String]` - - `message: String` + List of allowed tool names. - The error message. + - `never: Never{ read_only, tool_names}` - - `type: :error` + A filter object to specify which tools are allowed. - The object type, which was always `error` for moderation failures. + - `read_only: bool` - - `:error` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `previous_response_id: String` + - `tool_names: Array[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`. + List of allowed tool names. - - `prompt: BetaResponsePrompt` + - `McpToolApprovalSetting = :always | :never` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + 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 identifier of the prompt template to use. + - `:never` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `server_description: 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. + Optional description of the MCP server, used to provide more context. - - `String = String` + - `server_url: String` - - `class BetaResponseInputText` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A text input to the model. + - `tunnel_id: String` - - `class BetaResponseInputImage` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class CodeInterpreter` - - `class BetaResponseInputFile` + A tool that runs Python code to help generate a response to a prompt. - A file input to the model. + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - - `version: String` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - Optional version of the prompt template. + - `String = String` - - `prompt_cache_key: String` + The container ID. - 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). + - `class CodeInterpreterToolAuto` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `type: :auto` - - `mode: :implicit | :explicit` + Always `auto`. - Whether implicit prompt-cache breakpoints were enabled. + - `:auto` - - `:implicit` + - `file_ids: Array[String]` - - `:explicit` + An optional list of uploaded files to make available to your code. - - `ttl: :"30m"` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The minimum lifetime applied to each cache breakpoint. + The memory limit for the code interpreter container. - - `:"30m"` + - `:"1g"` - - `prompt_cache_retention: :in_memory | :"24h"` + - `:"4g"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `:"16g"` - 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. + - `:"64g"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Network access policy for the container. - - `:in_memory` + - `class BetaContainerNetworkPolicyDisabled` - - `:"24h"` + - `type: :disabled` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + Disable outbound network access. Always `disabled`. - **gpt-5 and o-series models only** + - `:disabled` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `class BetaContainerNetworkPolicyAllowlist` - - `context: :auto | :current_turn | :all_turns` + - `allowed_domains: Array[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. + A list of allowed domains when type is `allowlist`. - - `:auto` + - `type: :allowlist` - - `:current_turn` + Allow outbound network access only to specified domains. Always `allowlist`. - - `:all_turns` + - `:allowlist` - - `effort: :none | :minimal | :low | 4 more` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - 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. + Optional domain-scoped secrets for allowlisted domains. - - `:none` + - `domain: String` - - `:minimal` + The domain associated with the secret. - - `:low` + - `name: String` - - `:medium` + The name of the secret to inject for the domain. - - `:high` + - `value: String` - - `:xhigh` + The secret value to inject for the domain. - - `:max` + - `type: :code_interpreter` - - `generate_summary: :auto | :concise | :detailed` + The type of the code interpreter tool. Always `code_interpreter`. - **Deprecated:** use `summary` instead. + - `:code_interpreter` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `allowed_callers: Array[:direct | :programmatic]` - - `:auto` + The tool invocation context(s). - - `:concise` + - `:direct` - - `:detailed` + - `:programmatic` - - `mode: String | :standard | :pro` + - `class ProgrammaticToolCalling` - Controls the reasoning execution mode for the request. + - `type: :programmatic_tool_calling` - When returned on a response, this is the effective execution mode. + The type of the tool. Always `programmatic_tool_calling`. - - `String = String` + - `:programmatic_tool_calling` - - `Mode = :standard | :pro` + - `class ImageGeneration` - Controls the reasoning execution mode for the request. + A tool that generates images using the GPT image models. - When returned on a response, this is the effective execution mode. + - `type: :image_generation` - - `:standard` + The type of the image generation tool. Always `image_generation`. - - `:pro` + - `:image_generation` - - `summary: :auto | :concise | :detailed` + - `action: :generate | :edit | :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`. + Whether to generate a new image or edit an existing image. Default: `auto`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `:generate` + + - `:edit` - `:auto` - - `:concise` + - `background: :transparent | :opaque | :auto` - - `:detailed` + 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. - - `safety_identifier: 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. - 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). + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `service_tier: :auto | :default | :flex | 2 more` + - `:transparent` - Specifies the processing type used for serving the request. + - `:opaque` - - 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'. + - `: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. + - `input_fidelity: :high | :low` - - `: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`. - - `:default` + - `:high` - - `:flex` + - `:low` - - `:scale` + - `input_image_mask: InputImageMask{ file_id, image_url}` - - `:priority` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `status: BetaResponseStatus` + - `file_id: String` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + File ID for the mask image. - - `:completed` + - `image_url: String` - - `:failed` + Base64-encoded mask image. - - `:in_progress` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `:cancelled` + The image generation model to use. Default: `gpt-image-1`. - - `:queued` + - `String = String` - - `:incomplete` + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `text: BetaResponseTextConfig` + The image generation model to use. Default: `gpt-image-1`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `:"gpt-image-1"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `:"gpt-image-1-mini"` - - `format_: BetaResponseFormatTextConfig` + - `:"gpt-image-2"` - An object specifying the format that the model must output. + - `:"gpt-image-2-2026-04-21"` - 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). + - `:"gpt-image-1.5"` - The default format is `{ "type": "text" }` with no additional options. + - `:"chatgpt-image-latest"` - **Not recommended for gpt-4o and newer models:** + - `moderation: :auto | :low` - 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. + Moderation level for the generated image. Default: `auto`. - - `class Text` + - `:auto` - Default response format. Used to generate text responses. + - `:low` - - `type: :text` + - `output_compression: Integer` - The type of response format being defined. Always `text`. + Compression level for the output image. Default: 100. - - `:text` + - `output_format: :png | :webp | :jpeg` - - `class BetaResponseFormatTextJSONSchemaConfig` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:png` - - `name: String` + - `:webp` - 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. + - `:jpeg` - - `schema: Hash[Symbol, untyped]` + - `partial_images: Integer` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: :json_schema` + - `quality: :low | :medium | :high | :auto` - The type of response format being defined. Always `json_schema`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `:json_schema` + - `:low` - - `description: String` + - `:medium` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `:high` + + - `:auto` + + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 = String` - - `strict: bool` + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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). + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class JSONObject` + - `:"1024x1024"` - 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. + - `:"1024x1536"` - - `type: :json_object` + - `:"1536x1024"` - The type of response format being defined. Always `json_object`. + - `:auto` - - `:json_object` + - `class LocalShell` - - `verbosity: :low | :medium | :high` + A tool that allows the model to execute shell commands in a local environment. - 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: :local_shell` - - `:low` + The type of the local shell tool. Always `local_shell`. - - `:medium` + - `:local_shell` - - `:high` + - `class BetaFunctionShellTool` - - `top_logprobs: Integer` + A tool that allows the model to execute shell commands. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `type: :shell` - - `truncation: :auto | :disabled` + The type of the shell tool. Always `shell`. - The truncation strategy to use for the model response. + - `:shell` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `allowed_callers: Array[:direct | :programmatic]` - - `:auto` + The tool invocation context(s). - - `:disabled` + - `:direct` - - `usage: BetaResponseUsage` + - `:programmatic` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `input_tokens: Integer` + - `class BetaContainerAuto` - The number of input tokens. + - `type: :container_auto` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + Automatically creates a container for this request - A detailed breakdown of the input tokens. + - `:container_auto` - - `cache_write_tokens: Integer` + - `file_ids: Array[String]` - The number of input tokens that were written to the cache. + An optional list of uploaded files to make available to your code. - - `cached_tokens: Integer` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The memory limit for the container. - - `output_tokens: Integer` + - `:"1g"` - The number of output tokens. + - `:"4g"` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `:"16g"` - A detailed breakdown of the output tokens. + - `:"64g"` - - `reasoning_tokens: Integer` + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - The number of reasoning tokens. + Network access policy for the container. - - `total_tokens: Integer` + - `class BetaContainerNetworkPolicyDisabled` - The total number of tokens used. + - `class BetaContainerNetworkPolicyAllowlist` - - `user: String` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - 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). + An optional list of skills referenced by id or inline data. - - `sequence_number: Integer` + - `class BetaSkillReference` - The sequence number for this event. + - `skill_id: String` - - `type: :"response.completed"` + The ID of the referenced skill. - The type of the event. Always `response.completed`. + - `type: :skill_reference` - - `:"response.completed"` + References a skill created with the /v1/skills endpoint. - - `agent: Agent{ agent_name}` + - `:skill_reference` - The agent that owns this multi-agent streaming event. + - `version: 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. + - `class BetaInlineSkill` - - `class BetaResponseContentPartAddedEvent` + - `description: String` - Emitted when a new content part is added. + The description of the skill. - - `content_index: Integer` + - `name: String` - The index of the content part that was added. + The name of the skill. - - `item_id: String` + - `source: BetaInlineSkillSource` - The ID of the output item that the content part was added to. + Inline skill payload - - `output_index: Integer` + - `data: String` - The index of the output item that the content part was added to. + Base64-encoded skill zip bundle. - - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` + - `media_type: :"application/zip"` - The content part that was added. + The media type of the inline skill payload. Must be `application/zip`. - - `class BetaResponseOutputText` + - `:"application/zip"` - A text output from the model. + - `type: :base64` - - `class BetaResponseOutputRefusal` + The type of the inline skill source. Must be `base64`. - A refusal from the model. + - `:base64` - - `class ReasoningText` + - `type: :inline` - Reasoning text from the model. + Defines an inline skill for this request. - - `text: String` + - `:inline` - The reasoning text from the model. + - `class BetaLocalEnvironment` - - `type: :reasoning_text` + - `type: :local` - The type of the reasoning text. Always `reasoning_text`. + Use a local computer environment. - - `:reasoning_text` + - `:local` - - `sequence_number: Integer` + - `skills: Array[BetaLocalSkill]` - The sequence number of this event. + An optional list of skills. - - `type: :"response.content_part.added"` + - `description: String` - The type of the event. Always `response.content_part.added`. + The description of the skill. - - `:"response.content_part.added"` + - `name: String` - - `agent: Agent{ agent_name}` + The name of the skill. - The agent that owns this multi-agent streaming event. + - `path: String` - - `agent_name: String` + The path to the directory containing the skill. - The canonical name of the agent that produced this item. + - `class BetaContainerReference` - - `class BetaResponseContentPartDoneEvent` + - `container_id: String` - Emitted when a content part is done. + The ID of the referenced container. - - `content_index: Integer` + - `type: :container_reference` - The index of the content part that is done. + References a container created with the /v1/containers endpoint - - `item_id: String` + - `:container_reference` - The ID of the output item that the content part was added to. + - `class BetaCustomTool` - - `output_index: Integer` + 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 index of the output item that the content part was added to. + - `name: String` - - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` + The name of the custom tool, used to identify it in tool calls. - The content part that is done. + - `type: :custom` - - `class BetaResponseOutputText` + The type of the custom tool. Always `custom`. - A text output from the model. + - `:custom` - - `class BetaResponseOutputRefusal` + - `allowed_callers: Array[:direct | :programmatic]` - A refusal from the model. + The tool invocation context(s). - - `class ReasoningText` + - `:direct` - Reasoning text from the model. + - `:programmatic` - - `text: String` + - `defer_loading: bool` - The reasoning text from the model. + Whether this tool should be deferred and discovered via tool search. - - `type: :reasoning_text` + - `description: String` - The type of the reasoning text. Always `reasoning_text`. + Optional description of the custom tool, used to provide more context. - - `:reasoning_text` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `sequence_number: Integer` + The input format for the custom tool. Default is unconstrained text. - The sequence number of this event. + - `class Text` - - `type: :"response.content_part.done"` + Unconstrained free-form text. - The type of the event. Always `response.content_part.done`. + - `type: :text` - - `:"response.content_part.done"` + Unconstrained text format. Always `text`. - - `agent: Agent{ agent_name}` + - `:text` - The agent that owns this multi-agent streaming event. + - `class Grammar` - - `agent_name: String` + A grammar defined by the user. - The canonical name of the agent that produced this item. + - `definition: String` - - `class BetaResponseCreatedEvent` + The grammar definition. - An event that is emitted when a response is created. + - `syntax: :lark | :regex` - - `response: BetaResponse` + The syntax of the grammar definition. One of `lark` or `regex`. - The response that was created. + - `:lark` - - `sequence_number: Integer` + - `:regex` - The sequence number for this event. + - `type: :grammar` - - `type: :"response.created"` + Grammar format. Always `grammar`. - The type of the event. Always `response.created`. + - `:grammar` - - `:"response.created"` + - `class BetaNamespaceTool` - - `agent: Agent{ 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` - - `class BetaResponseErrorEvent` + The namespace name used in tool calls (for example, `crm`). - Emitted when an error occurs. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `code: String` + The function/custom tools available inside this namespace. - The error code. + - `class Function` - - `message: String` + - `name: String` - The error message. + - `type: :function` - - `param: String` + - `:function` - The error parameter. + - `allowed_callers: Array[:direct | :programmatic]` - - `sequence_number: Integer` + The tool invocation context(s). - The sequence number of this event. + - `:direct` - - `type: :error` + - `:programmatic` - The type of the event. Always `error`. + - `defer_loading: bool` - - `:error` + Whether this function should be deferred and discovered via tool search. - - `agent: Agent{ agent_name}` + - `description: String` - The agent that owns this multi-agent streaming event. + - `output_schema: Hash[Symbol, untyped]` - - `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: untyped` - - `class BetaResponseFileSearchCallCompletedEvent` + - `strict: bool` - Emitted when a file search call is completed (results found). + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `item_id: String` + - `class BetaCustomTool` - The ID of the output item that the file search call is initiated. + 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) - - `output_index: Integer` + - `type: :namespace` - The index of the output item that the file search call is initiated. + The type of the tool. Always `namespace`. - - `sequence_number: Integer` + - `:namespace` - The sequence number of this event. + - `class BetaToolSearchTool` - - `type: :"response.file_search_call.completed"` + Hosted or BYOT tool search configuration for deferred tools. - The type of the event. Always `response.file_search_call.completed`. + - `type: :tool_search` - - `:"response.file_search_call.completed"` + The type of the tool. Always `tool_search`. - - `agent: Agent{ agent_name}` + - `:tool_search` - The agent that owns this multi-agent streaming event. + - `description: 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: :server | :client` - - `class BetaResponseFileSearchCallInProgressEvent` + Whether tool search is executed by the server or by the client. - Emitted when a file search call is initiated. + - `:server` - - `item_id: String` + - `:client` - The ID of the output item that the file search call is initiated. + - `parameters: untyped` - - `output_index: Integer` + Parameter schema for a client-executed tool search tool. - The index of the output item that the file search call is initiated. + - `class BetaWebSearchPreviewTool` - - `sequence_number: Integer` + 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 sequence number of this event. + - `type: :web_search_preview | :web_search_preview_2025_03_11` - - `type: :"response.file_search_call.in_progress"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the event. Always `response.file_search_call.in_progress`. + - `:web_search_preview` - - `:"response.file_search_call.in_progress"` + - `:web_search_preview_2025_03_11` - - `agent: Agent{ agent_name}` + - `search_content_types: Array[:text | :image]` - The agent that owns this multi-agent streaming event. + - `:text` - - `agent_name: String` + - `:image` - The canonical name of the agent that produced this item. + - `search_context_size: :low | :medium | :high` - - `class BetaResponseFileSearchCallSearchingEvent` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Emitted when a file search is currently searching. + - `:low` - - `item_id: String` + - `:medium` - The ID of the output item that the file search call is initiated. + - `:high` - - `output_index: Integer` + - `user_location: UserLocation{ type, city, country, 2 more}` - The index of the output item that the file search call is searching. + The user's location. - - `sequence_number: Integer` + - `type: :approximate` - The sequence number of this event. + The type of location approximation. Always `approximate`. - - `type: :"response.file_search_call.searching"` + - `:approximate` - The type of the event. Always `response.file_search_call.searching`. + - `city: String` - - `:"response.file_search_call.searching"` + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: Agent{ agent_name}` + - `country: 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: String` - The canonical name of the agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseFunctionCallArgumentsDeltaEvent` + - `timezone: String` - Emitted when there is a partial function-call arguments delta. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `delta: String` + - `class BetaApplyPatchTool` - The function-call arguments delta that is added. + Allows the assistant to create, delete, or update files using unified diffs. - - `item_id: String` + - `type: :apply_patch` - The ID of the output item that the function-call arguments delta is added to. + The type of the tool. Always `apply_patch`. - - `output_index: Integer` + - `:apply_patch` - The index of the output item that the function-call arguments delta is added to. + - `allowed_callers: Array[:direct | :programmatic]` - - `sequence_number: Integer` + The tool invocation context(s). - The sequence number of this event. + - `:direct` - - `type: :"response.function_call_arguments.delta"` + - `:programmatic` - The type of the event. Always `response.function_call_arguments.delta`. +### Beta Tool Choice Allowed - - `:"response.function_call_arguments.delta"` +- `class BetaToolChoiceAllowed` - - `agent: Agent{ agent_name}` + Constrains the tools available to the model to a pre-defined set. - The agent that owns this multi-agent streaming event. + - `mode: :auto | :required` - - `agent_name: String` + Constrains the tools available to the model to a pre-defined set. - The canonical name of the agent that produced this item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `class BetaResponseFunctionCallArgumentsDoneEvent` + `required` requires the model to call one or more of the allowed tools. - Emitted when function-call arguments are finalized. + - `:auto` - - `arguments: String` + - `:required` - The function-call arguments. + - `tools: Array[Hash[Symbol, untyped]]` - - `item_id: String` + A list of tool definitions that the model should be allowed to call. - The ID of the item. + For the Responses API, the list of tool definitions might look like: - - `name: String` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The name of the function that was called. + - `type: :allowed_tools` - - `output_index: Integer` + Allowed tool configuration type. Always `allowed_tools`. - The index of the output item. + - `:allowed_tools` - - `sequence_number: Integer` +### Beta Tool Choice Apply Patch - The sequence number of this event. +- `class BetaToolChoiceApplyPatch` - - `type: :"response.function_call_arguments.done"` + Forces the model to call the apply_patch tool when executing a tool call. - - `:"response.function_call_arguments.done"` + - `type: :apply_patch` - - `agent: Agent{ agent_name}` + The tool to call. Always `apply_patch`. - The agent that owns this multi-agent streaming event. + - `:apply_patch` - - `agent_name: String` +### Beta Tool Choice Custom - The canonical name of the agent that produced this item. +- `class BetaToolChoiceCustom` - - `class BetaResponseInProgressEvent` + Use this option to force the model to call a specific custom tool. - Emitted when the response is in progress. + - `name: String` - - `response: BetaResponse` + The name of the custom tool to call. - The response that is in progress. + - `type: :custom` - - `sequence_number: Integer` + For custom tool calling, the type is always `custom`. - The sequence number of this event. + - `:custom` - - `type: :"response.in_progress"` +### Beta Tool Choice Function - The type of the event. Always `response.in_progress`. +- `class BetaToolChoiceFunction` - - `:"response.in_progress"` + Use this option to force the model to call a specific function. - - `agent: Agent{ agent_name}` + - `name: String` - The agent that owns this multi-agent streaming event. + The name of the function to call. - - `agent_name: String` + - `type: :function` - The canonical name of the agent that produced this item. + For function calling, the type is always `function`. - - `class BetaResponseFailedEvent` + - `:function` - An event that is emitted when a response fails. +### Beta Tool Choice Mcp - - `response: BetaResponse` +- `class BetaToolChoiceMcp` - The response that failed. + Use this option to force the model to call a specific tool on a remote MCP server. - - `sequence_number: Integer` + - `server_label: String` - The sequence number of this event. + The label of the MCP server to use. - - `type: :"response.failed"` + - `type: :mcp` - The type of the event. Always `response.failed`. + For MCP tools, the type is always `mcp`. - - `:"response.failed"` + - `:mcp` - - `agent: Agent{ agent_name}` + - `name: String` - The agent that owns this multi-agent streaming event. + The name of the tool to call on the server. - - `agent_name: String` +### Beta Tool Choice Options - The canonical name of the agent that produced this item. +- `BetaToolChoiceOptions = :none | :auto | :required` - - `class BetaResponseIncompleteEvent` + Controls which (if any) tool is called by the model. - An event that is emitted when a response finishes as incomplete. + `none` means the model will not call any tool and instead generates a message. - - `response: BetaResponse` + `auto` means the model can pick between generating a message or calling one or + more tools. - The response that was incomplete. + `required` means the model must call one or more tools. - - `sequence_number: Integer` + - `:none` - The sequence number of this event. + - `:auto` - - `type: :"response.incomplete"` + - `:required` - The type of the event. Always `response.incomplete`. +### Beta Tool Choice Shell - - `:"response.incomplete"` +- `class BetaToolChoiceShell` - - `agent: Agent{ agent_name}` + Forces the model to call the shell tool when a tool call is required. - The agent that owns this multi-agent streaming event. + - `type: :shell` - - `agent_name: String` + The tool to call. Always `shell`. - The canonical name of the agent that produced this item. + - `:shell` - - `class BetaResponseOutputItemAddedEvent` +### Beta Tool Choice Types - Emitted when a new output item is added. +- `class BetaToolChoiceTypes` - - `item: BetaResponseOutputItem` + 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). - The output item that was added. + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `class BetaResponseOutputMessage` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - An output message from the model. + Allowed values are: - - `class BetaResponseFileSearchToolCall` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - 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` - - `class BetaResponseFunctionToolCall` + - `:web_search_preview` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `:computer` - - `class BetaResponseFunctionToolCallOutputItem` + - `:computer_use_preview` - - `class AgentMessage` + - `:computer_use` - - `class MultiAgentCall` + - `:web_search_preview_2025_03_11` - - `class MultiAgentCallOutput` + - `:image_generation` - - `class BetaResponseFunctionWebSearch` + - `: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. +### Beta Tool Search Tool - - `class BetaResponseComputerToolCall` +- `class BetaToolSearchTool` - 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. - - `class BetaResponseComputerToolCallOutputItem` + - `type: :tool_search` - - `class BetaResponseReasoningItem` + The type of the tool. Always `tool_search`. - 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). + - `:tool_search` - - `class Program` + - `description: String` - - `class ProgramOutput` + Description shown to the model for a client-executed tool search tool. - - `class BetaResponseToolSearchCall` + - `execution: :server | :client` - - `class BetaResponseToolSearchOutputItem` + Whether tool search is executed by the server or by the client. - - `class AdditionalTools` + - `:server` - - `class BetaResponseCompactionItem` + - `:client` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `parameters: untyped` - - `class ImageGenerationCall` + Parameter schema for a client-executed tool search tool. - An image generation request made by the model. +### Beta Web Search Preview Tool - - `class BetaResponseCodeInterpreterToolCall` +- `class BetaWebSearchPreviewTool` - A tool call to run code. + 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). - - `class LocalShellCall` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - A tool call to run a command on the local shell. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `class LocalShellCallOutput` + - `:web_search_preview` - The output of a local shell tool call. + - `:web_search_preview_2025_03_11` - - `class BetaResponseFunctionShellToolCall` + - `search_content_types: Array[:text | :image]` - A tool call that executes one or more shell commands in a managed environment. + - `:text` - - `class BetaResponseFunctionShellToolCallOutput` + - `:image` - The output of a shell tool call that was emitted. + - `search_context_size: :low | :medium | :high` - - `class BetaResponseApplyPatchToolCall` + High 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 applies file diffs by creating, deleting, or updating files. + - `:low` - - `class BetaResponseApplyPatchToolCallOutput` + - `:medium` - The output emitted by an apply patch tool call. + - `:high` - - `class McpCall` + - `user_location: UserLocation{ type, city, country, 2 more}` - An invocation of a tool on an MCP server. + The user's location. - - `class McpListTools` + - `type: :approximate` - A list of tools available on an MCP server. + The type of location approximation. Always `approximate`. - - `class McpApprovalRequest` + - `:approximate` - A request for human approval of a tool invocation. + - `city: String` - - `class McpApprovalResponse` + Free text input for the city of the user, e.g. `San Francisco`. - A response to an MCP approval request. + - `country: String` - - `class BetaResponseCustomToolCall` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A call to a custom tool created by the model. + - `region: String` - - `class BetaResponseCustomToolCallOutputItem` + Free text input for the region of the user, e.g. `California`. - The output of a custom tool call from your code, being sent back to the model. + - `timezone: String` - - `output_index: Integer` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The index of the output item that was added. +### Beta Web Search Tool - - `sequence_number: Integer` +- `class BetaWebSearchTool` - The sequence number of this event. + 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: :"response.output_item.added"` + - `type: :web_search | :web_search_2025_08_26` - The type of the event. Always `response.output_item.added`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `:"response.output_item.added"` + - `:web_search` - - `agent: Agent{ agent_name}` + - `:web_search_2025_08_26` - The agent that owns this multi-agent streaming event. + - `filters: Filters{ allowed_domains}` - - `agent_name: String` + Filters for the search. - The canonical name of the agent that produced this item. + - `allowed_domains: Array[String]` - - `class BetaResponseOutputItemDoneEvent` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Emitted when an output item is marked done. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `item: BetaResponseOutputItem` + - `search_context_size: :low | :medium | :high` - The output item that was marked done. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `output_index: Integer` + - `:low` - The index of the output item that was marked done. + - `:medium` - - `sequence_number: Integer` + - `:high` - The sequence number of this event. + - `user_location: UserLocation{ city, country, region, 2 more}` - - `type: :"response.output_item.done"` + The approximate location of the user. - The type of the event. Always `response.output_item.done`. + - `city: String` - - `:"response.output_item.done"` + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: Agent{ agent_name}` + - `country: 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: String` - The canonical name of the agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseReasoningSummaryPartAddedEvent` + - `timezone: String` - Emitted when a new reasoning summary part is added. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `item_id: String` + - `type: :approximate` - The ID of the item this summary part is associated with. + The type of location approximation. Always `approximate`. - - `output_index: Integer` + - `:approximate` - The index of the output item this summary part is associated with. +# Input Items - - `part: Part{ text, type}` +## List input items - The summary part that was added. +`beta.responses.input_items.list(response_id, **kwargs) -> CursorPage` - - `text: String` +**get** `/responses/{response_id}/input_items?beta=true` - The text of the summary part. +Returns a list of input items for a given response. - - `type: :summary_text` +### Parameters - The type of the summary part. Always `summary_text`. +- `response_id: String` - - `:summary_text` +- `after: String` - - `sequence_number: Integer` + An item ID to list items after, used in pagination. - The sequence number of this event. +- `include: Array[BetaResponseIncludable]` - - `summary_index: Integer` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - The index of the summary part within the reasoning summary. + - `:"file_search_call.results"` - - `type: :"response.reasoning_summary_part.added"` + - `:"web_search_call.results"` - The type of the event. Always `response.reasoning_summary_part.added`. + - `:"web_search_call.action.sources"` - - `:"response.reasoning_summary_part.added"` + - `:"message.input_image.image_url"` - - `agent: Agent{ agent_name}` + - `:"computer_call_output.output.image_url"` - The agent that owns this multi-agent streaming event. + - `:"code_interpreter_call.outputs"` - - `agent_name: String` + - `:"reasoning.encrypted_content"` - The canonical name of the agent that produced this item. + - `:"message.output_text.logprobs"` - - `class BetaResponseReasoningSummaryPartDoneEvent` +- `limit: Integer` - Emitted when a reasoning summary part is completed. + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - - `item_id: String` +- `order: :asc | :desc` - The ID of the item this summary part is associated with. + The order to return the input items in. Default is `desc`. - - `output_index: Integer` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - The index of the output item this summary part is associated with. + - `:asc` - - `part: Part{ text, type}` + - `:desc` - The completed summary part. +- `betas: Array[:"responses_multi_agent=v1"]` - - `text: String` + - `:"responses_multi_agent=v1"` - The text of the summary part. +### Returns - - `type: :summary_text` +- `BetaResponseItem = BetaResponseInputMessageItem | BetaResponseOutputMessage | BetaResponseFileSearchToolCall | 29 more` - The type of the summary part. Always `summary_text`. + Content item used to generate a response. - - `:summary_text` + - `class BetaResponseInputMessageItem` - - `sequence_number: Integer` + - `id: String` - The sequence number of this event. + The unique ID of the message input. - - `summary_index: Integer` + - `content: BetaResponseInputMessageContentList` - The index of the summary part within the reasoning summary. + A list of one or many input items to the model, containing different content + types. - - `type: :"response.reasoning_summary_part.done"` + - `class BetaResponseInputText` - The type of the event. Always `response.reasoning_summary_part.done`. + A text input to the model. - - `:"response.reasoning_summary_part.done"` + - `text: String` - - `agent: Agent{ agent_name}` + The text input to the model. - The agent that owns this multi-agent streaming event. + - `type: :input_text` - - `agent_name: String` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `:input_text` - - `status: :incomplete` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + Marks the exact end of a reusable 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` - - `class BetaResponseReasoningSummaryTextDeltaEvent` + The breakpoint mode. Always `explicit`. - Emitted when a delta is added to a reasoning summary text. + - `:explicit` - - `delta: String` + - `class BetaResponseInputImage` - The text delta that was added to the summary. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `item_id: String` + - `detail: :low | :high | :auto | :original` - The ID of the item this summary text delta is associated with. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `output_index: Integer` + - `:low` - The index of the output item this summary text delta is associated with. + - `:high` - - `sequence_number: Integer` + - `:auto` - The sequence number of this event. + - `:original` - - `summary_index: Integer` + - `type: :input_image` - The index of the summary part within the reasoning summary. + The type of the input item. Always `input_image`. - - `type: :"response.reasoning_summary_text.delta"` + - `:input_image` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `file_id: String` - - `:"response.reasoning_summary_text.delta"` + The ID of the file to be sent to the model. - - `agent: Agent{ agent_name}` + - `image_url: String` - The agent that owns this multi-agent streaming event. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent_name: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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. - - `class BetaResponseReasoningSummaryTextDoneEvent` + - `mode: :explicit` - Emitted when a reasoning summary text is completed. + The breakpoint mode. Always `explicit`. - - `item_id: String` + - `:explicit` - The ID of the item this summary text is associated with. + - `class BetaResponseInputFile` - - `output_index: Integer` + A file input to the model. - The index of the output item this summary text is associated with. + - `type: :input_file` - - `sequence_number: Integer` + The type of the input item. Always `input_file`. - The sequence number of this event. + - `:input_file` - - `summary_index: Integer` + - `detail: :auto | :low | :high` - The index of the summary part within the reasoning summary. + 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` - The full text of the completed reasoning summary. + - `:low` - - `type: :"response.reasoning_summary_text.done"` + - `:high` - The type of the event. Always `response.reasoning_summary_text.done`. + - `file_data: String` - - `:"response.reasoning_summary_text.done"` + The content of the file to be sent to the model. - - `agent: Agent{ agent_name}` + - `file_id: 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: String` - The canonical name of the agent that produced this item. + The URL of the file to be sent to the model. - - `class BetaResponseReasoningTextDeltaEvent` + - `filename: String` - Emitted when a delta is added to a reasoning text. + The name of the file to be sent to the model. - - `content_index: Integer` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The index of the reasoning content part this delta is associated with. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `delta: String` + - `mode: :explicit` - The text delta that was added to the reasoning content. + The breakpoint mode. Always `explicit`. - - `item_id: String` + - `:explicit` - The ID of the item this reasoning text delta is associated with. + - `role: :user | :system | :developer` - - `output_index: Integer` + The role of the message input. One of `user`, `system`, or `developer`. - The index of the output item this reasoning text delta is associated with. + - `:user` - - `sequence_number: Integer` + - `:system` - The sequence number of this event. + - `:developer` - - `type: :"response.reasoning_text.delta"` + - `type: :message` - The type of the event. Always `response.reasoning_text.delta`. + The type of the message input. Always set to `message`. - - `:"response.reasoning_text.delta"` + - `:message` - `agent: Agent{ 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. - - `class BetaResponseReasoningTextDoneEvent` + - `status: :in_progress | :completed | :incomplete` - Emitted when a reasoning text is completed. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `content_index: Integer` + - `:in_progress` - The index of the reasoning content part. + - `:completed` - - `item_id: String` + - `:incomplete` - The ID of the item this reasoning text is associated with. + - `class BetaResponseOutputMessage` - - `output_index: Integer` + An output message from the model. - The index of the output item this reasoning text is associated with. + - `id: String` - - `sequence_number: Integer` + The unique ID of the output message. - The sequence number of this event. + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - - `text: String` + The content of the output message. - The full text of the completed reasoning content. + - `class BetaResponseOutputText` - - `type: :"response.reasoning_text.done"` + A text output from the model. - The type of the event. Always `response.reasoning_text.done`. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:"response.reasoning_text.done"` + The annotations of the text output. - - `agent: Agent{ agent_name}` + - `class FileCitation` - The agent that owns this multi-agent streaming event. + A citation to a file. - - `agent_name: String` + - `file_id: String` - The canonical name of the agent that produced this item. + The ID of the file. - - `class BetaResponseRefusalDeltaEvent` + - `filename: String` - Emitted when there is a partial refusal text. + The filename of the file cited. - - `content_index: Integer` + - `index: Integer` - The index of the content part that the refusal text is added to. + The index of the file in the list of files. - - `delta: String` + - `type: :file_citation` - The refusal text that is added. + The type of the file citation. Always `file_citation`. - - `item_id: String` + - `:file_citation` - The ID of the output item that the refusal text is added to. + - `class URLCitation` - - `output_index: Integer` + A citation for a web resource used to generate a model response. - The index of the output item that the refusal text is added to. + - `end_index: Integer` - - `sequence_number: Integer` + The index of the last character of the URL citation in the message. - The sequence number of this event. + - `start_index: Integer` - - `type: :"response.refusal.delta"` + The index of the first character of the URL citation in the message. - The type of the event. Always `response.refusal.delta`. + - `title: String` - - `:"response.refusal.delta"` + The title of the web resource. - - `agent: Agent{ agent_name}` + - `type: :url_citation` - The agent that owns this multi-agent streaming event. + The type of the URL citation. Always `url_citation`. - - `agent_name: String` + - `:url_citation` - The canonical name of the agent that produced this item. + - `url: String` - - `class BetaResponseRefusalDoneEvent` + The URL of the web resource. - Emitted when refusal text is finalized. + - `class ContainerFileCitation` - - `content_index: Integer` + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. - The index of the content part that the refusal text is finalized. + - `end_index: Integer` - - `item_id: String` + The index of the last character of the container file citation in the message. - The ID of the output item that the refusal text is finalized. + - `file_id: String` - - `output_index: Integer` + The ID of the file. - The index of the output item that the refusal text is finalized. + - `filename: String` - - `refusal: String` + The filename of the container file cited. - The refusal text that is finalized. + - `start_index: Integer` - - `sequence_number: Integer` + The index of the first character of the container file citation in the message. - The sequence number of this event. + - `type: :container_file_citation` - - `type: :"response.refusal.done"` + The type of the container file citation. Always `container_file_citation`. - The type of the event. Always `response.refusal.done`. + - `:container_file_citation` - - `:"response.refusal.done"` + - `class FilePath` - - `agent: Agent{ agent_name}` + A path to a file. - The agent that owns this multi-agent streaming event. + - `file_id: String` - - `agent_name: String` + The ID of the file. - The canonical name of the agent that produced this item. + - `index: Integer` - - `class BetaResponseTextDeltaEvent` + The index of the file in the list of files. - Emitted when there is an additional text delta. + - `type: :file_path` - - `content_index: Integer` + The type of the file path. Always `file_path`. - The index of the content part that the text delta was added to. + - `:file_path` - - `delta: String` + - `text: String` - The text delta that was added. + The text output from the model. - - `item_id: String` + - `type: :output_text` - The ID of the output item that the text delta was added to. + The type of the output text. Always `output_text`. - - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` + - `:output_text` - The log probabilities of the tokens in the delta. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - `token: String` - A possible text token. + - `bytes: Array[Integer]` - `logprob: Float` - The log probability of this token. - - - `top_logprobs: Array[TopLogprob{ token, logprob}]` - - The log probabilities of up to 20 of the most likely tokens. + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - `token: String` - A possible text token. + - `bytes: Array[Integer]` - `logprob: Float` - The log probability of this token. + - `class BetaResponseOutputRefusal` - - `output_index: Integer` + A refusal from the model. - The index of the output item that the text delta was added to. + - `refusal: String` - - `sequence_number: Integer` + The refusal explanation from the model. - The sequence number for this event. + - `type: :refusal` - - `type: :"response.output_text.delta"` + The type of the refusal. Always `refusal`. - The type of the event. Always `response.output_text.delta`. + - `:refusal` - - `:"response.output_text.delta"` + - `role: :assistant` - - `agent: Agent{ agent_name}` + The role of the output message. Always `assistant`. - The agent that owns this multi-agent streaming event. + - `:assistant` - - `agent_name: String` + - `status: :in_progress | :completed | :incomplete` - The canonical name of the agent that produced this item. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class BetaResponseTextDoneEvent` + - `:in_progress` - Emitted when text content is finalized. + - `:completed` - - `content_index: Integer` + - `:incomplete` - The index of the content part that the text content is finalized. + - `type: :message` - - `item_id: String` + The type of the output message. Always `message`. - The ID of the output item that the text content is finalized. + - `:message` - - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` + - `agent: Agent{ agent_name}` - The log probabilities of the tokens in the delta. + The agent that produced this item. - - `token: String` + - `agent_name: String` - A possible text token. + The canonical name of the agent that produced this item. - - `logprob: Float` + - `phase: :commentary | :final_answer` - The log probability of this token. + 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: Array[TopLogprob{ token, logprob}]` + - `:commentary` - The log probabilities of up to 20 of the most likely tokens. + - `:final_answer` - - `token: String` + - `class BetaResponseFileSearchToolCall` - A possible text token. + 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. - - `logprob: Float` + - `id: String` - The log probability of this token. + The unique ID of the file search tool call. - - `output_index: Integer` + - `queries: Array[String]` - The index of the output item that the text content is finalized. + The queries used to search for files. - - `sequence_number: Integer` + - `status: :in_progress | :searching | :completed | 2 more` - The sequence number for this event. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `text: String` + - `:in_progress` - The text content that is finalized. + - `:searching` - - `type: :"response.output_text.done"` + - `:completed` - The type of the event. Always `response.output_text.done`. + - `:incomplete` - - `:"response.output_text.done"` + - `:failed` + + - `type: :file_search_call` + + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` - `agent: Agent{ 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. - - `class BetaResponseWebSearchCallCompletedEvent` - - Emitted when a web search call is completed. - - - `item_id: String` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - Unique ID for the output item associated with the web search call. + The results of the file search tool call. - - `output_index: Integer` + - `attributes: Hash[Symbol, String | Float | bool]` - The index of the output item that the web search call 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. - - `sequence_number: Integer` + - `String = String` - The sequence number of the web search call being processed. + - `Float = Float` - - `type: :"response.web_search_call.completed"` + - `UnionMember2 = bool` - The type of the event. Always `response.web_search_call.completed`. + - `file_id: String` - - `:"response.web_search_call.completed"` + The unique ID of the file. - - `agent: Agent{ agent_name}` + - `filename: String` - The agent that owns this multi-agent streaming event. + The name of the file. - - `agent_name: String` + - `score: Float` - The canonical name of the agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `class BetaResponseWebSearchCallInProgressEvent` + - `text: String` - Emitted when a web search call is initiated. + The text that was retrieved from the file. - - `item_id: String` + - `class BetaResponseComputerToolCall` - Unique ID for the output item associated with the web search call. + 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. - - `output_index: Integer` + - `id: String` - The index of the output item that the web search call is associated with. + The unique ID of the computer call. - - `sequence_number: Integer` + - `call_id: String` - The sequence number of the web search call being processed. + An identifier used when responding to the tool call with output. - - `type: :"response.web_search_call.in_progress"` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - The type of the event. Always `response.web_search_call.in_progress`. + The pending safety checks for the computer call. - - `:"response.web_search_call.in_progress"` + - `id: String` - - `agent: Agent{ agent_name}` + The ID of the pending safety check. - The agent that owns this multi-agent streaming event. + - `code: String` - - `agent_name: String` + The type of the pending safety check. - The canonical name of the agent that produced this item. + - `message: String` - - `class BetaResponseWebSearchCallSearchingEvent` + Details about the pending safety check. - Emitted when a web search call is executing. + - `status: :in_progress | :completed | :incomplete` - - `item_id: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unique ID for the output item associated with the web search call. + - `:in_progress` - - `output_index: Integer` + - `:completed` - The index of the output item that the web search call is associated with. + - `:incomplete` - - `sequence_number: Integer` + - `type: :computer_call` - The sequence number of the web search call being processed. + The type of the computer call. Always `computer_call`. - - `type: :"response.web_search_call.searching"` + - `:computer_call` - The type of the event. Always `response.web_search_call.searching`. + - `action: BetaComputerAction` - - `:"response.web_search_call.searching"` + A click action. - - `agent: Agent{ agent_name}` + - `class Click` - The agent that owns this multi-agent streaming event. + A click action. - - `agent_name: String` + - `button: :left | :right | :wheel | 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`. - - `class BetaResponseImageGenCallCompletedEvent` + - `:left` - Emitted when an image generation tool call has completed and the final image is available. + - `:right` - - `item_id: String` + - `:wheel` - The unique identifier of the image generation item being processed. + - `:back` - - `output_index: Integer` + - `:forward` - The index of the output item in the response's output array. + - `type: :click` - - `sequence_number: Integer` + Specifies the event type. For a click action, this property is always `click`. - The sequence number of this event. + - `:click` - - `type: :"response.image_generation_call.completed"` + - `x: Integer` - The type of the event. Always 'response.image_generation_call.completed'. + The x-coordinate where the click occurred. - - `:"response.image_generation_call.completed"` + - `y_: Integer` - - `agent: Agent{ agent_name}` + The y-coordinate where the click occurred. - The agent that owns this multi-agent streaming event. + - `keys: Array[String]` - - `agent_name: String` + The keys being held while clicking. - The canonical name of the agent that produced this item. + - `class DoubleClick` - - `class BetaResponseImageGenCallGeneratingEvent` + A double click action. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `keys: Array[String]` - - `item_id: String` + The keys being held while double-clicking. - The unique identifier of the image generation item being processed. + - `type: :double_click` - - `output_index: Integer` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The index of the output item in the response's output array. + - `:double_click` - - `sequence_number: Integer` + - `x: Integer` - The sequence number of the image generation item being processed. + The x-coordinate where the double click occurred. - - `type: :"response.image_generation_call.generating"` + - `y_: Integer` - The type of the event. Always 'response.image_generation_call.generating'. + The y-coordinate where the double click occurred. - - `:"response.image_generation_call.generating"` + - `class Drag` - - `agent: Agent{ agent_name}` + A drag action. - The agent that owns this multi-agent streaming event. + - `path: Array[Path{ x, y_}]` - - `agent_name: String` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The canonical name of the agent that produced this item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `class BetaResponseImageGenCallInProgressEvent` + - `x: Integer` - Emitted when an image generation tool call is in progress. + The x-coordinate. - - `item_id: String` + - `y_: Integer` - The unique identifier of the image generation item being processed. + The y-coordinate. - - `output_index: Integer` + - `type: :drag` - The index of the output item in the response's output array. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `sequence_number: Integer` + - `:drag` - The sequence number of the image generation item being processed. + - `keys: Array[String]` - - `type: :"response.image_generation_call.in_progress"` + The keys being held while dragging the mouse. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `class Keypress` - - `:"response.image_generation_call.in_progress"` + A collection of keypresses the model would like to perform. - - `agent: Agent{ agent_name}` + - `keys: Array[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`. - - `class BetaResponseImageGenCallPartialImageEvent` + - `:keypress` - Emitted when a partial image is available during image generation streaming. + - `class Move` - - `item_id: String` + A mouse move action. - The unique identifier of the image generation item being processed. + - `type: :move` - - `output_index: Integer` + Specifies the event type. For a move action, this property is always set to `move`. - The index of the output item in the response's output array. + - `:move` - - `partial_image_b64: String` + - `x: Integer` - Base64-encoded partial image data, suitable for rendering as an image. + The x-coordinate to move to. - - `partial_image_index: Integer` + - `y_: Integer` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + The y-coordinate to move to. - - `sequence_number: Integer` + - `keys: Array[String]` - The sequence number of the image generation item being processed. + The keys being held while moving the mouse. - - `type: :"response.image_generation_call.partial_image"` + - `class Screenshot` - The type of the event. Always 'response.image_generation_call.partial_image'. + A screenshot action. - - `:"response.image_generation_call.partial_image"` + - `type: :screenshot` - - `agent: Agent{ agent_name}` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The agent that owns this multi-agent streaming event. + - `:screenshot` - - `agent_name: String` + - `class Scroll` - The canonical name of the agent that produced this item. + A scroll action. - - `class BetaResponseMcpCallArgumentsDeltaEvent` + - `scroll_x: Integer` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + The horizontal scroll distance. - - `delta: String` + - `scroll_y: Integer` - A JSON string containing the partial update to the arguments for the MCP tool call. + The vertical scroll distance. - - `item_id: String` + - `type: :scroll` - The unique identifier of the MCP tool call item being processed. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `output_index: Integer` + - `:scroll` - The index of the output item in the response's output array. + - `x: Integer` - - `sequence_number: Integer` + The x-coordinate where the scroll occurred. - The sequence number of this event. + - `y_: Integer` - - `type: :"response.mcp_call_arguments.delta"` + The y-coordinate where the scroll occurred. - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `keys: Array[String]` - - `:"response.mcp_call_arguments.delta"` + The keys being held while scrolling. - - `agent: Agent{ agent_name}` + - `class 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. - - `class BetaResponseMcpCallArgumentsDoneEvent` + - `type: :type` - Emitted when the arguments for an MCP tool call are finalized. + Specifies the event type. For a type action, this property is always set to `type`. - - `arguments: String` + - `:type` - A JSON string containing the finalized arguments for the MCP tool call. + - `class Wait` - - `item_id: String` + A wait action. - The unique identifier of the MCP tool call item being processed. + - `type: :wait` - - `output_index: Integer` + Specifies the event type. For a wait action, this property is always set to `wait`. - The index of the output item in the response's output array. + - `:wait` - - `sequence_number: Integer` + - `actions: BetaComputerActionList` - The sequence number of this event. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: :"response.mcp_call_arguments.done"` + - `class Click` - The type of the event. Always 'response.mcp_call_arguments.done'. + A click action. - - `:"response.mcp_call_arguments.done"` + - `class DoubleClick` - - `agent: Agent{ agent_name}` + A double click action. - The agent that owns this multi-agent streaming event. + - `class Drag` - - `agent_name: String` + A drag action. - The canonical name of the agent that produced this item. + - `class Keypress` - - `class BetaResponseMcpCallCompletedEvent` + A collection of keypresses the model would like to perform. - Emitted when an MCP tool call has completed successfully. + - `class Move` - - `item_id: String` + A mouse move action. - The ID of the MCP tool call item that completed. + - `class Screenshot` - - `output_index: Integer` + A screenshot action. - The index of the output item that completed. + - `class Scroll` - - `sequence_number: Integer` + A scroll action. - The sequence number of this event. + - `class Type` - - `type: :"response.mcp_call.completed"` + An action to type in text. - The type of the event. Always 'response.mcp_call.completed'. + - `class Wait` - - `:"response.mcp_call.completed"` + A wait action. - `agent: Agent{ 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. - - `class BetaResponseMcpCallFailedEvent` + - `class BetaResponseComputerToolCallOutputItem` - Emitted when an MCP tool call has failed. + - `id: String` - - `item_id: String` + The unique ID of the computer call tool output. - The ID of the MCP tool call item that failed. + - `call_id: String` - - `output_index: Integer` + The ID of the computer tool call that produced the output. - The index of the output item that failed. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `sequence_number: Integer` + A computer screenshot image used with the computer use tool. - The sequence number of this event. + - `type: :computer_screenshot` - - `type: :"response.mcp_call.failed"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The type of the event. Always 'response.mcp_call.failed'. + - `:computer_screenshot` - - `:"response.mcp_call.failed"` + - `file_id: String` - - `agent: Agent{ agent_name}` + The identifier of an uploaded file that contains the screenshot. - The agent that owns this multi-agent streaming event. + - `image_url: String` - - `agent_name: String` + The URL of the screenshot image. - The canonical name of the agent that produced this item. + - `status: :completed | :incomplete | :failed | :in_progress` - - `class BetaResponseMcpCallInProgressEvent` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Emitted when an MCP tool call is in progress. + - `:completed` - - `item_id: String` + - `:incomplete` - The unique identifier of the MCP tool call item being processed. + - `:failed` - - `output_index: Integer` + - `:in_progress` - The index of the output item in the response's output array. + - `type: :computer_call_output` - - `sequence_number: Integer` + The type of the computer tool call output. Always `computer_call_output`. - The sequence number of this event. + - `:computer_call_output` - - `type: :"response.mcp_call.in_progress"` + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The type of the event. Always 'response.mcp_call.in_progress'. + The safety checks reported by the API that have been acknowledged by the + developer. - - `:"response.mcp_call.in_progress"` + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. - `agent: Agent{ 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. - - `class BetaResponseMcpListToolsCompletedEvent` + - `created_by: 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` + - `class BetaResponseFunctionWebSearch` - The ID of the MCP tool call item that produced this output. + 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. - - `output_index: Integer` + - `id: String` - The index of the output item that was processed. + The unique ID of the web search tool call. - - `sequence_number: Integer` + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` - The sequence number of this 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). - - `type: :"response.mcp_list_tools.completed"` + - `class Search` - The type of the event. Always 'response.mcp_list_tools.completed'. + Action type "search" - Performs a web search query. - - `:"response.mcp_list_tools.completed"` + - `type: :search` - - `agent: Agent{ agent_name}` + The action type. - The agent that owns this multi-agent streaming event. + - `:search` - - `agent_name: String` + - `queries: Array[String]` - The canonical name of the agent that produced this item. + The search queries. - - `class BetaResponseMcpListToolsFailedEvent` + - `query: String` - Emitted when the attempt to list available MCP tools has failed. + The search query. - - `item_id: String` + - `sources: Array[Source{ type, url}]` - The ID of the MCP tool call item that failed. + The sources used in the search. - - `output_index: Integer` + - `type: :url` - The index of the output item that failed. + The type of source. Always `url`. - - `sequence_number: Integer` + - `:url` - The sequence number of this event. + - `url: String` - - `type: :"response.mcp_list_tools.failed"` + The URL of the source. - The type of the event. Always 'response.mcp_list_tools.failed'. + - `class OpenPage` - - `:"response.mcp_list_tools.failed"` + Action type "open_page" - Opens a specific URL from search results. - - `agent: Agent{ agent_name}` + - `type: :open_page` - The agent that owns this multi-agent streaming event. + The action type. - - `agent_name: String` + - `:open_page` - The canonical name of the agent that produced this item. + - `url: String` - - `class BetaResponseMcpListToolsInProgressEvent` + The URL opened by the model. - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `class FindInPage` - - `item_id: String` + Action type "find_in_page": Searches for a pattern within a loaded page. - The ID of the MCP tool call item that is being processed. + - `pattern: String` - - `output_index: Integer` + The pattern or text to search for within the page. - The index of the output item that is being processed. + - `type: :find_in_page` - - `sequence_number: Integer` + The action type. - The sequence number of this event. + - `:find_in_page` - - `type: :"response.mcp_list_tools.in_progress"` + - `url: String` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + The URL of the page searched for the pattern. - - `:"response.mcp_list_tools.in_progress"` + - `status: :in_progress | :searching | :completed | :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: Agent{ 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. - - `class BetaResponseOutputTextAnnotationAddedEvent` + - `class BetaResponseFunctionToolCallItem` - Emitted when an annotation is added to output text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `annotation: untyped` + - `id: String` - The annotation object being added. (See annotation schema for details.) + The unique ID of the function tool call. - - `annotation_index: Integer` + - `status: :in_progress | :completed | :incomplete` - The index of the annotation within the content part. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `content_index: Integer` + - `:in_progress` - The index of the content part within the output item. + - `:completed` - - `item_id: String` + - `:incomplete` - The unique identifier of the item to which the annotation is being added. + - `created_by: String` - - `output_index: Integer` + The identifier of the actor that created the item. - The index of the output item in the response's output array. + - `class BetaResponseFunctionToolCallOutputItem` - - `sequence_number: Integer` + - `id: String` - The sequence number of this event. + The unique ID of the function call tool output. - - `type: :"response.output_text.annotation.added"` + - `call_id: String` - The type of the event. Always 'response.output_text.annotation.added'. + The unique ID of the function tool call generated by the model. - - `:"response.output_text.annotation.added"` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `agent: Agent{ agent_name}` + The output from the function call generated by your code. + Can be a string or an list of output content. - The agent that owns this multi-agent streaming event. + - `String = String` - - `agent_name: String` + A string of the output of the function call. - The canonical name of the agent that produced this item. + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `class BetaResponseQueuedEvent` + Text, image, or file output of the function call. - Emitted when a response is queued and waiting to be processed. + - `class BetaResponseInputText` - - `response: BetaResponse` + A text input to the model. - The full response object that is queued. + - `class BetaResponseInputImage` - - `sequence_number: Integer` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The sequence number for this event. + - `class BetaResponseInputFile` - - `type: :"response.queued"` + A file input to the model. - The type of the event. Always 'response.queued'. + - `status: :in_progress | :completed | :incomplete` - - `:"response.queued"` + 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 function tool call output. Always `function_call_output`. + + - `:function_call_output` - `agent: Agent{ 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. - - `class BetaResponseCustomToolCallInputDeltaEvent` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Event representing a delta (partial update) to the input of a custom tool call. + The execution context that produced this tool call. - - `delta: String` + - `class Direct` - The incremental input data (delta) for the custom tool call. + - `type: :direct` - - `item_id: String` + The caller type. Always `direct`. - Unique identifier for the API item associated with this event. + - `:direct` - - `output_index: Integer` + - `class Program` - The index of the output this delta applies to. + - `caller_id: String` - - `sequence_number: Integer` + The call ID of the program item that produced this tool call. - The sequence number of this event. + - `type: :program` - - `type: :"response.custom_tool_call_input.delta"` + The caller type. Always `program`. - The event type identifier. + - `:program` - - `:"response.custom_tool_call_input.delta"` + - `created_by: String` - - `agent: Agent{ agent_name}` + The identifier of the actor that created the item. - The agent that owns this multi-agent streaming event. + - `class AgentMessage` - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The unique ID of the agent message. - - `class BetaResponseCustomToolCallInputDoneEvent` + - `author: String` - Event indicating that input for a custom tool call is complete. + The sending agent identity. - - `input: String` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - The complete input data for the custom tool call. + Encrypted content sent between agents. - - `item_id: String` + - `class BetaResponseInputText` - Unique identifier for the API item associated with this event. + A text input to the model. - - `output_index: Integer` + - `class BetaResponseOutputText` - The index of the output this event applies to. + A text output from the model. - - `sequence_number: Integer` + - `class Text` - The sequence number of this event. + A text content. - - `type: :"response.custom_tool_call_input.done"` + - `text: String` - The event type identifier. + - `type: :text` - - `:"response.custom_tool_call_input.done"` + - `:text` - - `agent: Agent{ agent_name}` + - `class SummaryText` - The agent that owns this multi-agent streaming event. + A summary text from the model. - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. -### Beta Response Text Config + - `type: :summary_text` -- `class BetaResponseTextConfig` + The type of the object. Always `summary_text`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `:summary_text` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `class ReasoningText` - - `format_: BetaResponseFormatTextConfig` + Reasoning text from the model. - An object specifying the format that the model must output. + - `text: 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 reasoning text from the model. - The default format is `{ "type": "text" }` with no additional options. + - `type: :reasoning_text` - **Not recommended for gpt-4o and newer models:** + The type of the reasoning text. Always `reasoning_text`. - 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. + - `:reasoning_text` - - `class Text` + - `class BetaResponseOutputRefusal` - Default response format. Used to generate text responses. + A refusal from the model. - - `type: :text` + - `class BetaResponseInputImage` - The type of response format being defined. Always `text`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:text` + - `class ComputerScreenshot` - - `class BetaResponseFormatTextJSONSchemaConfig` + A screenshot of a computer. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `detail: :low | :high | :auto | :original` - - `name: String` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `:low` - - `schema: Hash[Symbol, untyped]` + - `:high` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `:auto` - - `type: :json_schema` + - `:original` - The type of response format being defined. Always `json_schema`. + - `file_id: String` - - `:json_schema` + The identifier of an uploaded file that contains the screenshot. - - `description: String` + - `image_url: String` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The URL of the screenshot image. - - `strict: bool` + - `type: :computer_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](https://platform.openai.com/docs/guides/structured-outputs). + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `class JSONObject` + - `: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. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `type: :json_object` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of response format being defined. Always `json_object`. + - `mode: :explicit` - - `:json_object` + The breakpoint mode. Always `explicit`. - - `verbosity: :low | :medium | :high` + - `:explicit` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `class BetaResponseInputFile` - - `:low` + A file input to the model. - - `:medium` + - `class EncryptedContent` - - `:high` + Opaque encrypted content that Responses API decrypts inside trusted model execution. -### Beta Response Text Delta Event + - `encrypted_content: String` -- `class BetaResponseTextDeltaEvent` + Opaque encrypted content. - Emitted when there is an additional text delta. + - `type: :encrypted_content` - - `content_index: Integer` + The type of the input item. Always `encrypted_content`. - The index of the content part that the text delta was added to. + - `:encrypted_content` - - `delta: String` + - `recipient: String` - The text delta that was added. + The destination agent identity. - - `item_id: String` + - `type: :agent_message` - The ID of the output item that the text delta was added to. + The type of the item. Always `agent_message`. - - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` + - `:agent_message` - The log probabilities of the tokens in the delta. + - `agent: Agent{ agent_name}` - - `token: String` + The agent that produced this item. - A possible text token. + - `agent_name: String` - - `logprob: Float` + The canonical name of the agent that produced this item. - The log probability of this token. + - `class MultiAgentCall` - - `top_logprobs: Array[TopLogprob{ token, logprob}]` + - `id: String` - The log probabilities of up to 20 of the most likely tokens. + The unique ID of the multi-agent call item. - - `token: String` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - A possible text token. + The multi-agent action to execute. - - `logprob: Float` + - `:spawn_agent` - The log probability of this token. + - `:interrupt_agent` - - `output_index: Integer` + - `:list_agents` - The index of the output item that the text delta was added to. + - `:send_message` - - `sequence_number: Integer` + - `:followup_task` - The sequence number for this event. + - `:wait_agent` - - `type: :"response.output_text.delta"` + - `arguments: String` - The type of the event. Always `response.output_text.delta`. + The JSON string of arguments generated for the action. - - `:"response.output_text.delta"` + - `call_id: String` - - `agent: Agent{ agent_name}` + The unique ID linking this call to its output. - The agent that owns this multi-agent streaming event. + - `type: :multi_agent_call` - - `agent_name: String` + The type of the multi-agent call. Always `multi_agent_call`. - The canonical name of the agent that produced this item. + - `:multi_agent_call` -### Beta Response Text Done Event + - `agent: Agent{ agent_name}` -- `class BetaResponseTextDoneEvent` + The agent that produced this item. - Emitted when text content is finalized. + - `agent_name: String` - - `content_index: Integer` + The canonical name of the agent that produced this item. - The index of the content part that the text content is finalized. + - `class MultiAgentCallOutput` - - `item_id: String` + - `id: String` - The ID of the output item that the text content is finalized. + The unique ID of the multi-agent call output item. - - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The log probabilities of the tokens in the delta. + The multi-agent action that produced this result. - - `token: String` + - `:spawn_agent` - A possible text token. + - `:interrupt_agent` - - `logprob: Float` + - `:list_agents` - The log probability of this token. + - `:send_message` - - `top_logprobs: Array[TopLogprob{ token, logprob}]` + - `:followup_task` - The log probabilities of up to 20 of the most likely tokens. + - `:wait_agent` - - `token: String` + - `call_id: String` - A possible text token. + The unique ID of the multi-agent call. - - `logprob: Float` + - `output: Array[BetaResponseOutputText]` - The log probability of this token. + Text output returned by the multi-agent action. - - `output_index: Integer` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - The index of the output item that the text content is finalized. + The annotations of the text output. - - `sequence_number: Integer` + - `text: String` - The sequence number for this event. + The text output from the model. - - `text: String` + - `type: :output_text` - The text content that is finalized. + The type of the output text. Always `output_text`. - - `type: :"response.output_text.done"` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - The type of the event. Always `response.output_text.done`. + - `type: :multi_agent_call_output` - - `:"response.output_text.done"` + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `:multi_agent_call_output` - `agent: Agent{ 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 Tool Search Call - -- `class BetaResponseToolSearchCall` + - `class BetaResponseToolSearchCall` - `id: String` @@ -132656,9 +145416,7 @@ puts(beta_compacted_response) The identifier of the actor that created the item. -### Beta Response Tool Search Output Item - -- `class BetaResponseToolSearchOutputItem` + - `class BetaResponseToolSearchOutputItem` - `id: String` @@ -132787,7 +145545,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -132797,7 +145555,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -132844,7 +145606,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -132854,7 +145616,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -133794,1400 +146560,1167 @@ puts(beta_compacted_response) The identifier of the actor that created the item. -### Beta Response Tool Search Output Item Param - -- `class BetaResponseToolSearchOutputItemParam` - - - `tools: Array[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool` - - 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: Hash[Symbol, untyped]` + - `class AdditionalTools` - A JSON schema object describing the parameters of the function. + - `id: String` - - `strict: bool` + The unique ID of the additional tools item. - Whether strict parameter validation is enforced for this function tool. + - `role: :unknown | :user | :assistant | 5 more` - - `type: :function` + The role that provided the additional tools. - The type of the function tool. Always `function`. + - `:unknown` - - `:function` + - `:user` - - `allowed_callers: Array[:direct | :programmatic]` + - `:assistant` - The tool invocation context(s). + - `:system` - - `:direct` + - `:critic` - - `:programmatic` + - `:discriminator` - - `defer_loading: bool` + - `:developer` - Whether this function is deferred and loaded via tool search. + - `:tool` - - `description: String` + - `tools: Array[BetaTool]` - A description of the function. Used by the model to determine whether or not to call the function. + The additional tool definitions made available at this item. - - `output_schema: Hash[Symbol, untyped]` + - `class BetaFunctionTool` - A JSON schema object describing the JSON value encoded in string outputs for this 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). - `class BetaFileSearchTool` 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[String]` - - The IDs of the vector stores to search. - - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - - A filter to apply. - - - `class ComparisonFilter` - - 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 | :ne | :gt | 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 | Float | bool | Array[untyped]` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `String = String` - - - `Float = Float` - - - `UnionMember2 = bool` - - - `UnionMember3 = Array[untyped]` - - - `class CompoundFilter` - - Combine multiple filters using `and` or `or`. - - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `class ComparisonFilter` - - 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 | :ne | :gt | 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 | Float | bool | Array[untyped]` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `String = String` - - - `Float = Float` - - - `UnionMember2 = bool` - - - `UnionMember3 = Array[untyped]` - - - `UnionMember1 = untyped` - - - `type: :and | :or` - - Type of operation: `and` or `or`. - - - `:and` - - - `:or` - - - `max_num_results: Integer` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - - Ranking options for search. - - - `hybrid_search: HybridSearch{ 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: Float` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: Float` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: :auto | :"default-2024-11-15"` - - The ranker to use for the file search. - - - `:auto` - - - `:"default-2024-11-15"` - - - `score_threshold: Float` - - 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. - - `class BetaComputerTool` 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` - - `class BetaComputerUsePreviewTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `display_height: Integer` - - The height of the computer display. - - - `display_width: Integer` - - The width of the computer display. - - - `environment: :windows | :mac | :linux | 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` - - `class BetaWebSearchTool` 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 | :web_search_2025_08_26` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `class Mcp` - - `:web_search` + 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). - - `:web_search_2025_08_26` + - `class CodeInterpreter` - - `filters: Filters{ allowed_domains}` + A tool that runs Python code to help generate a response to a prompt. - Filters for the search. + - `class ProgrammaticToolCalling` - - `allowed_domains: Array[String]` + - `class ImageGeneration` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A tool that generates images using the GPT image models. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `class LocalShell` - - `search_context_size: :low | :medium | :high` + A tool that allows the model to execute shell commands in a local environment. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `class BetaFunctionShellTool` - - `:low` + A tool that allows the model to execute shell commands. - - `:medium` + - `class BetaCustomTool` - - `:high` + 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_location: UserLocation{ city, country, region, 2 more}` + - `class BetaNamespaceTool` - The approximate location of the user. + Groups function/custom tools under a shared namespace. - - `city: String` + - `class BetaToolSearchTool` - Free text input for the city of the user, e.g. `San Francisco`. + Hosted or BYOT tool search configuration for deferred tools. - - `country: String` + - `class BetaWebSearchPreviewTool` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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). - - `region: String` + - `class BetaApplyPatchTool` - Free text input for the region of the user, e.g. `California`. + Allows the assistant to create, delete, or update files using unified diffs. - - `timezone: String` + - `type: :additional_tools` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the item. Always `additional_tools`. - - `type: :approximate` + - `:additional_tools` - The type of location approximation. Always `approximate`. + - `agent: Agent{ agent_name}` - - `:approximate` + The agent that produced this item. - - `class Mcp` + - `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` + - `class BetaResponseReasoningItem` - A label for this MCP server, 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: :mcp` + - `id: String` - The type of the MCP tool. Always `mcp`. + The unique identifier of the reasoning content. - - `:mcp` + - `summary: Array[Summary{ text, type}]` - - `allowed_callers: Array[:direct | :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` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + The type of the object. Always `summary_text`. - List of allowed tool names or a filter object. + - `:summary_text` - - `McpAllowedTools = Array[String]` + - `type: :reasoning` - A string array of allowed tool names + The type of the object. Always `reasoning`. - - `class McpToolFilter` + - `:reasoning` - A filter object to specify which tools are allowed. + - `agent: Agent{ agent_name}` - - `read_only: bool` + 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: Array[String]` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `content: Array[Content{ text, type}]` - - `authorization: String` + Reasoning text 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. + - `text: String` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + The reasoning text from 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). + - `type: :reasoning_text` - Currently supported `connector_id` values are: + The type of the reasoning text. Always `reasoning_text`. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `:reasoning_text` - - `:connector_dropbox` + - `encrypted_content: String` - - `:connector_gmail` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `:connector_googlecalendar` + - `status: :in_progress | :completed | :incomplete` - - `:connector_googledrive` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:connector_microsoftteams` + - `:in_progress` - - `:connector_outlookcalendar` + - `:completed` - - `:connector_outlookemail` + - `:incomplete` - - `:connector_sharepoint` + - `class Program` - - `defer_loading: bool` + - `id: String` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the program item. - - `headers: Hash[Symbol, String]` + - `call_id: String` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The stable call ID of the program item. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `code: String` - Specify which of the MCP server's tools require approval. + The JavaScript source executed by programmatic tool calling. - - `class McpToolApprovalFilter` + - `fingerprint: 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. + Opaque program replay fingerprint that must be round-tripped. - - `always: Always{ read_only, tool_names}` + - `type: :program` - A filter object to specify which tools are allowed. + The type of the item. Always `program`. - - `read_only: bool` + - `: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. + - `agent: Agent{ agent_name}` - - `tool_names: Array[String]` + The agent that produced this item. - List of allowed tool names. + - `agent_name: String` - - `never: Never{ read_only, tool_names}` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `class ProgramOutput` - - `read_only: bool` + - `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 program output item. - - `tool_names: Array[String]` + - `call_id: String` - List of allowed tool names. + The call ID of the program item. - - `McpToolApprovalSetting = :always | :never` + - `result: 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 result produced by the program item. - - `:always` + - `status: :completed | :incomplete` - - `:never` + The terminal status of the program output item. - - `server_description: String` + - `:completed` - Optional description of the MCP server, used to provide more context. + - `:incomplete` - - `server_url: String` + - `type: :program_output` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The type of the item. Always `program_output`. - - `tunnel_id: String` + - `:program_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. + - `agent: Agent{ agent_name}` - - `class CodeInterpreter` + 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 | CodeInterpreterToolAuto{ 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. + - `class BetaResponseCompactionItem` - - `String = String` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The container ID. + - `id: String` - - `class CodeInterpreterToolAuto` + The unique ID of the compaction item. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `encrypted_content: String` - - `type: :auto` + The encrypted content that was produced by compaction. - Always `auto`. + - `type: :compaction` - - `:auto` + The type of the item. Always `compaction`. - - `file_ids: Array[String]` + - `:compaction` - An optional list of uploaded files to make available to your code. + - `agent: Agent{ agent_name}` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"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"` + - `created_by: String` - - `:"16g"` + The identifier of the actor that created the item. - - `:"64g"` + - `class ImageGenerationCall` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + An image generation request made by the model. - Network access policy for the container. + - `id: String` - - `class BetaContainerNetworkPolicyDisabled` + The unique ID of the image generation call. - - `type: :disabled` + - `result: String` - Disable outbound network access. Always `disabled`. + The generated image encoded in base64. - - `:disabled` + - `status: :in_progress | :completed | :generating | :failed` - - `class BetaContainerNetworkPolicyAllowlist` + The status of the image generation call. - - `allowed_domains: Array[String]` + - `:in_progress` - A list of allowed domains when type is `allowlist`. + - `:completed` - - `type: :allowlist` + - `:generating` - Allow outbound network access only to specified domains. Always `allowlist`. + - `:failed` - - `:allowlist` + - `type: :image_generation_call` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + The type of the image generation call. Always `image_generation_call`. - Optional domain-scoped secrets for allowlisted domains. + - `:image_generation_call` - - `domain: String` + - `agent: Agent{ agent_name}` - The domain associated with the secret. + The agent that produced this item. - - `name: String` + - `agent_name: String` - The name of the secret to inject for the domain. + The canonical name of the agent that produced this item. - - `value: String` + - `class BetaResponseCodeInterpreterToolCall` - The secret value to inject for the domain. + A tool call to run code. - - `type: :code_interpreter` + - `id: String` - The type of the code interpreter tool. Always `code_interpreter`. + The unique ID of the code interpreter tool call. - - `:code_interpreter` + - `code: String` - - `allowed_callers: Array[:direct | :programmatic]` + The code to run, or null if not available. - The tool invocation context(s). + - `container_id: String` - - `:direct` + The ID of the container used to run the code. - - `:programmatic` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `class ProgrammaticToolCalling` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: :programmatic_tool_calling` + - `class Logs` - The type of the tool. Always `programmatic_tool_calling`. + The logs output from the code interpreter. - - `:programmatic_tool_calling` + - `logs: String` - - `class ImageGeneration` + The logs output from the code interpreter. - A tool that generates images using the GPT image models. + - `type: :logs` - - `type: :image_generation` + The type of the output. Always `logs`. - The type of the image generation tool. Always `image_generation`. + - `:logs` - - `:image_generation` + - `class Image` - - `action: :generate | :edit | :auto` + The image output from the code interpreter. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: :image` - - `:generate` + The type of the output. Always `image`. - - `:edit` + - `:image` - - `:auto` + - `url: String` - - `background: :transparent | :opaque | :auto` + The URL of the image output from the 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. + - `status: :in_progress | :completed | :incomplete | 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. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - 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` + - `:interpreting` - - `input_fidelity: :high | :low` + - `:failed` - 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: :code_interpreter_call` - - `:high` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `:low` + - `:code_interpreter_call` - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `agent: Agent{ agent_name}` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The agent that produced this item. - - `file_id: String` + - `agent_name: String` - File ID for the mask image. + The canonical name of the agent that produced this item. - - `image_url: String` + - `class LocalShellCall` - Base64-encoded mask image. + A tool call to run a command on the local shell. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `id: String` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the local shell call. - - `String = String` + - `action: Action{ command, env, type, 3 more}` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + Execute a shell command on the server. - The image generation model to use. Default: `gpt-image-1`. + - `command: Array[String]` - - `:"gpt-image-1"` + The command to run. - - `:"gpt-image-1-mini"` + - `env: Hash[Symbol, String]` - - `:"gpt-image-2"` + Environment variables to set for the command. - - `:"gpt-image-2-2026-04-21"` + - `type: :exec` - - `:"gpt-image-1.5"` + The type of the local shell action. Always `exec`. - - `:"chatgpt-image-latest"` + - `:exec` - - `moderation: :auto | :low` + - `timeout_ms: Integer` - Moderation level for the generated image. Default: `auto`. + Optional timeout in milliseconds for the command. - - `:auto` + - `user: String` - - `:low` + Optional user to run the command as. - - `output_compression: Integer` + - `working_directory: String` - Compression level for the output image. Default: 100. + Optional working directory to run the command in. - - `output_format: :png | :webp | :jpeg` + - `call_id: String` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The unique ID of the local shell tool call generated by the model. - - `:png` + - `status: :in_progress | :completed | :incomplete` - - `:webp` + The status of the local shell call. - - `:jpeg` + - `:in_progress` - - `partial_images: Integer` + - `:completed` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `:incomplete` - - `quality: :low | :medium | :high | :auto` + - `type: :local_shell_call` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the local shell call. Always `local_shell_call`. - - `:low` + - `:local_shell_call` - - `:medium` + - `agent: Agent{ agent_name}` - - `:high` + The agent that produced this item. - - `:auto` + - `agent_name: String` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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`. + - `class LocalShellCallOutput` - - `String = String` + The output of a local shell tool call. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :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 local shell tool call generated by the model. - - `:"1024x1024"` + - `output: String` - - `:"1024x1536"` + A JSON string of the output of the local shell tool call. - - `:"1536x1024"` + - `type: :local_shell_call_output` - - `:auto` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `class LocalShell` + - `:local_shell_call_output` - A tool that allows the model to execute shell commands in a local environment. + - `agent: Agent{ agent_name}` - - `type: :local_shell` + The agent that produced this item. - The type of the local shell tool. Always `local_shell`. + - `agent_name: String` - - `:local_shell` + The canonical name of the agent that produced this item. - - `class BetaFunctionShellTool` + - `status: :in_progress | :completed | :incomplete` - A tool that allows the model to execute shell commands. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `type: :shell` + - `:in_progress` - The type of the shell tool. Always `shell`. + - `:completed` - - `:shell` + - `:incomplete` - - `allowed_callers: Array[:direct | :programmatic]` + - `class BetaResponseFunctionShellToolCall` - The tool invocation context(s). + A tool call that executes one or more shell commands in a managed environment. - - `:direct` + - `id: String` - - `:programmatic` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `action: Action{ commands, max_output_length, timeout_ms}` - - `class BetaContainerAuto` + The shell commands and limits that describe how to run the tool call. - - `type: :container_auto` + - `commands: Array[String]` - Automatically creates a container for this request + - `max_output_length: Integer` - - `:container_auto` + Optional maximum number of characters to return from each command. - - `file_ids: Array[String]` + - `timeout_ms: Integer` - An optional list of uploaded files to make available to your code. + Optional timeout in milliseconds for the commands. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `call_id: String` - The memory limit for the container. + The unique ID of the shell tool call generated by the model. - - `:"1g"` + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `:"4g"` + Represents the use of a local environment to perform shell actions. - - `:"16g"` + - `class BetaResponseLocalEnvironment` - - `:"64g"` + Represents the use of a local environment to perform shell actions. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `type: :local` - Network access policy for the container. + The environment type. Always `local`. - - `class BetaContainerNetworkPolicyDisabled` + - `:local` - - `class BetaContainerNetworkPolicyAllowlist` + - `class BetaResponseContainerReference` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + Represents a container created with /v1/containers. - An optional list of skills referenced by id or inline data. + - `container_id: String` - - `class BetaSkillReference` + - `type: :container_reference` - - `skill_id: String` + The environment type. Always `container_reference`. - The ID of the referenced skill. + - `:container_reference` - - `type: :skill_reference` + - `status: :in_progress | :completed | :incomplete` - References a skill created with the /v1/skills endpoint. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `:skill_reference` + - `:in_progress` - - `version: String` + - `:completed` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `:incomplete` - - `class BetaInlineSkill` + - `type: :shell_call` - - `description: String` + The type of the item. Always `shell_call`. - The description of the skill. + - `:shell_call` - - `name: String` + - `agent: Agent{ agent_name}` - The name of the skill. + The agent that produced this item. - - `source: BetaInlineSkillSource` + - `agent_name: String` - Inline skill payload + The canonical name of the agent that produced this item. - - `data: String` + - `caller_: Direct{ type} | Program{ caller_id, type}` - Base64-encoded skill zip bundle. + The execution context that produced this tool call. - - `media_type: :"application/zip"` + - `class Direct` - The media type of the inline skill payload. Must be `application/zip`. + - `type: :direct` - - `:"application/zip"` + - `:direct` - - `type: :base64` + - `class Program` - The type of the inline skill source. Must be `base64`. + - `caller_id: String` - - `:base64` + The call ID of the program item that produced this tool call. - - `type: :inline` + - `type: :program` - Defines an inline skill for this request. + - `:program` - - `:inline` + - `created_by: String` - - `class BetaLocalEnvironment` + The ID of the entity that created this tool call. - - `type: :local` + - `class BetaResponseFunctionShellToolCallOutput` - Use a local computer environment. + The output of a shell tool call that was emitted. - - `:local` + - `id: String` - - `skills: Array[BetaLocalSkill]` + The unique ID of the shell call output. Populated when this item is returned via API. - An optional list of skills. + - `call_id: String` - - `description: String` + The unique ID of the shell tool call generated by the model. - The description of the skill. + - `max_output_length: Integer` - - `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 name of the skill. + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` - - `path: String` + An array of shell call output contents - The path to the directory containing the skill. + - `outcome: Timeout{ type} | Exit{ exit_code, type}` - - `class BetaContainerReference` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `container_id: String` + - `class Timeout` - The ID of the referenced container. + Indicates that the shell call exceeded its configured time limit. - - `type: :container_reference` + - `type: :timeout` - References a container created with the /v1/containers endpoint + The outcome type. Always `timeout`. - - `:container_reference` + - `:timeout` - - `class BetaCustomTool` + - `class Exit` - 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) + Indicates that the shell commands finished and returned an exit code. - - `name: String` + - `exit_code: Integer` - The name of the custom tool, used to identify it in tool calls. + Exit code from the shell process. - - `type: :custom` + - `type: :exit` - The type of the custom tool. Always `custom`. + The outcome type. Always `exit`. - - `:custom` + - `:exit` - - `allowed_callers: Array[:direct | :programmatic]` + - `stderr: String` - The tool invocation context(s). + The standard error output that was captured. - - `:direct` + - `stdout: String` - - `:programmatic` + The standard output that was captured. - - `defer_loading: bool` + - `created_by: String` - Whether this tool should be deferred and discovered via tool search. + The identifier of the actor that created the item. - - `description: String` + - `status: :in_progress | :completed | :incomplete` - Optional description of the custom tool, used to provide more context. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `:in_progress` - The input format for the custom tool. Default is unconstrained text. + - `:completed` - - `class Text` + - `:incomplete` - Unconstrained free-form text. + - `type: :shell_call_output` - - `type: :text` + The type of the shell call output. Always `shell_call_output`. - Unconstrained text format. Always `text`. + - `:shell_call_output` - - `:text` + - `agent: Agent{ agent_name}` - - `class Grammar` + 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_: Direct{ type} | Program{ caller_id, type}` - - `syntax: :lark | :regex` + The execution context that produced this tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class Direct` - - `:lark` + - `type: :direct` - - `:regex` + - `:direct` - - `type: :grammar` + - `class Program` - Grammar format. Always `grammar`. + - `caller_id: String` - - `:grammar` + The call ID of the program item that produced this tool call. - - `class BetaNamespaceTool` + - `type: :program` - Groups function/custom tools under a shared namespace. + - `:program` - - `description: String` + - `created_by: String` - A description of the namespace shown to the model. + The identifier of the actor that created the item. - - `name: String` + - `class BetaResponseApplyPatchToolCall` - The namespace name used in tool calls (for example, `crm`). + A tool call that applies file diffs by creating, deleting, or updating files. - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `id: String` - The function/custom tools available inside this namespace. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `class Function` + - `call_id: String` - - `name: String` + The unique ID of the apply patch tool call generated by the model. - - `type: :function` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - - `:function` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `allowed_callers: Array[:direct | :programmatic]` + - `class CreateFile` - 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: bool` + - `path: String` - Whether this function should be deferred and discovered via tool search. + Path of the file to create. - - `description: String` + - `type: :create_file` - - `output_schema: Hash[Symbol, untyped]` + Create a new file with the provided diff. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `:create_file` - - `parameters: untyped` + - `class DeleteFile` - - `strict: bool` + Instruction describing how to delete a file via the apply_patch 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. + - `path: String` - - `class BetaCustomTool` + Path of the file to delete. - 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: :delete_file` - - `type: :namespace` + Delete the specified file. - The type of the tool. Always `namespace`. + - `:delete_file` - - `:namespace` + - `class UpdateFile` - - `class BetaToolSearchTool` + Instruction describing how to update a file via the apply_patch tool. - Hosted or BYOT tool search configuration for deferred tools. + - `diff: String` - - `type: :tool_search` + Diff to apply. - The type of the tool. Always `tool_search`. + - `path: String` - - `:tool_search` + Path of the file to update. - - `description: String` + - `type: :update_file` - Description shown to the model for a client-executed tool search tool. + Update an existing file with the provided diff. - - `execution: :server | :client` + - `:update_file` - Whether tool search is executed by the server or by the client. + - `status: :in_progress | :completed` - - `:server` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:client` + - `:in_progress` - - `parameters: untyped` + - `:completed` - Parameter schema for a client-executed tool search tool. + - `type: :apply_patch_call` - - `class BetaWebSearchPreviewTool` + The type of the item. Always `apply_patch_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). + - `:apply_patch_call` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `agent: Agent{ 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: Array[:text | :image]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:text` + The execution context that produced this tool call. - - `:image` + - `class Direct` - - `search_context_size: :low | :medium | :high` + - `type: :direct` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `:direct` - - `:low` + - `class Program` - - `:medium` + - `caller_id: String` - - `:high` + The call ID of the program item that produced this tool call. - - `user_location: UserLocation{ type, city, country, 2 more}` + - `type: :program` - The user's location. + - `:program` - - `type: :approximate` + - `created_by: String` - The type of location approximation. Always `approximate`. + The ID of the entity that created this tool call. - - `:approximate` + - `class BetaResponseApplyPatchToolCallOutput` - - `city: String` + The output emitted by an apply patch tool call. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: String` - - `country: String` + The unique ID of the apply patch tool call output. 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`. + - `call_id: String` - - `region: String` + The unique ID of the apply patch tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `status: :completed | :failed` - - `timezone: String` + The status of the apply patch tool call output. One of `completed` or `failed`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:completed` - - `class BetaApplyPatchTool` + - `:failed` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: :apply_patch_call_output` - - `type: :apply_patch` + The type of the item. Always `apply_patch_call_output`. - The type of the tool. Always `apply_patch`. + - `:apply_patch_call_output` - - `:apply_patch` + - `agent: Agent{ agent_name}` - - `allowed_callers: Array[:direct | :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_: Direct{ type} | Program{ caller_id, type}` - - `type: :tool_search_output` + The execution context that produced this tool call. - The item type. Always `tool_search_output`. + - `class Direct` - - `:tool_search_output` + - `type: :direct` - - `id: String` + - `:direct` - The unique ID of this tool search output. + - `class Program` - - `agent: Agent{ agent_name}` + - `caller_id: String` - The agent that produced this item. + The call ID of the program item that produced this tool call. - - `agent_name: String` + - `type: :program` - The canonical name of the agent that produced this item. + - `:program` - - `call_id: String` + - `created_by: String` - The unique ID of the tool search call generated by the model. + The ID of the entity that created this tool call output. - - `execution: :server | :client` + - `output: String` - Whether tool search was executed by the server or by the client. + Optional textual output returned by the apply patch tool. - - `:server` + - `class McpListTools` - - `:client` + A list of tools available on an MCP server. - - `status: :in_progress | :completed | :incomplete` + - `id: String` - The status of the tool search output. + The unique ID of the list. - - `:in_progress` + - `server_label: String` - - `:completed` + The label of the MCP server. - - `:incomplete` + - `tools: Array[Tool{ input_schema, name, annotations, description}]` -### Beta Response Usage + The tools available on the server. -- `class BetaResponseUsage` + - `input_schema: untyped` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The JSON schema describing the tool's input. - - `input_tokens: Integer` + - `name: String` - The number of input tokens. + The name of the tool. - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `annotations: untyped` - A detailed breakdown of the input tokens. + Additional annotations about the tool. - - `cache_write_tokens: Integer` + - `description: String` - The number of input tokens that were written to the cache. + The description of the tool. - - `cached_tokens: Integer` + - `type: :mcp_list_tools` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The type of the item. Always `mcp_list_tools`. - - `output_tokens: Integer` + - `:mcp_list_tools` - The number of output tokens. + - `agent: Agent{ agent_name}` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + The agent that produced this item. - A detailed breakdown of the output tokens. + - `agent_name: String` - - `reasoning_tokens: Integer` + The canonical name of the agent that produced this item. - The number of reasoning tokens. + - `error: String` - - `total_tokens: Integer` + Error message if the server could not list tools. - The total number of tokens used. + - `class McpApprovalRequest` -### Beta Response Web Search Call Completed Event + A request for human approval of a tool invocation. -- `class BetaResponseWebSearchCallCompletedEvent` + - `id: String` - Emitted when a web search call is completed. + The unique ID of the approval request. - - `item_id: String` + - `arguments: String` - Unique ID for the output item associated with the web search call. + A JSON string of arguments for the tool. - - `output_index: Integer` + - `name: String` - The index of the output item that the web search call is associated with. + The name of the tool to run. - - `sequence_number: Integer` + - `server_label: String` - The sequence number of the web search call being processed. + The label of the MCP server making the request. - - `type: :"response.web_search_call.completed"` + - `type: :mcp_approval_request` - The type of the event. Always `response.web_search_call.completed`. + The type of the item. Always `mcp_approval_request`. - - `:"response.web_search_call.completed"` + - `:mcp_approval_request` - `agent: Agent{ 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 Web Search Call In Progress Event - -- `class BetaResponseWebSearchCallInProgressEvent` + - `class McpApprovalResponse` - Emitted when a web search call is initiated. + A response to an MCP approval request. - - `item_id: String` + - `id: String` - Unique ID for the output item associated with the web search call. + The unique ID of the approval response - - `output_index: Integer` + - `approval_request_id: String` - The index of the output item that the web search call is associated with. + The ID of the approval request being answered. - - `sequence_number: Integer` + - `approve: bool` - The sequence number of the web search call being processed. + Whether the request was approved. - - `type: :"response.web_search_call.in_progress"` + - `type: :mcp_approval_response` - The type of the event. Always `response.web_search_call.in_progress`. + The type of the item. Always `mcp_approval_response`. - - `:"response.web_search_call.in_progress"` + - `:mcp_approval_response` - `agent: Agent{ 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 Web Search Call Searching Event + - `reason: String` -- `class BetaResponseWebSearchCallSearchingEvent` + Optional reason for the decision. - Emitted when a web search call is executing. + - `class McpCall` - - `item_id: String` + An invocation of a tool on an MCP server. - Unique ID for the output item associated with the web search call. + - `id: String` - - `output_index: Integer` + The unique ID of the tool call. - The index of the output item that the web search call is associated with. + - `arguments: String` - - `sequence_number: Integer` + A JSON string of the arguments passed to the tool. - The sequence number of the web search call being processed. + - `name: String` - - `type: :"response.web_search_call.searching"` + The name of the tool that was run. - The type of the event. Always `response.web_search_call.searching`. + - `server_label: String` - - `:"response.web_search_call.searching"` + The label of the MCP server running the tool. + + - `type: :mcp_call` + + The type of the item. Always `mcp_call`. + + - `:mcp_call` - `agent: Agent{ 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 Responses Client Event + - `approval_request_id: String` -- `BetaResponsesClientEvent = ResponseCreate{ type, background, context_management, 30 more} | ResponseInject{ input, response_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. - Client events accepted by the Responses WebSocket server. + - `error: String` - - `class ResponseCreate` + The error from the tool call, if any. - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`. + - `output: String` - Notes: + The output from the tool call. - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `type: :"response.create"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the client event. Always `response.create`. + - `:in_progress` - - `:"response.create"` + - `:completed` - - `background: bool` + - `:incomplete` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `:calling` - - `context_management: Array[ContextManagement{ type, compact_threshold}]` + - `:failed` - Context management configuration for this request. + - `class BetaResponseCustomToolCallItem` - - `type: String` + A call to a custom tool created by the model. - The context management entry type. Currently only 'compaction' is supported. + - `id: String` - - `compact_threshold: Integer` + The unique ID of the custom tool call item. - Token threshold at which compaction should be triggered for this entry. + - `status: :in_progress | :completed | :incomplete` - - `conversation: String | BetaResponseConversationParam` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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. + - `:in_progress` - - `String = String` + - `:completed` - The unique ID of the conversation. + - `:incomplete` - - `class BetaResponseConversationParam` + - `created_by: String` - The conversation that this response belongs to. + The identifier of the actor that created the item. - - `id: String` + - `class BetaResponseCustomToolCallOutputItem` - The unique ID of the conversation. + The output of a custom tool call from your code, being sent back to the model. - - `include: Array[BetaResponseIncludable]` + - `id: String` - Specify additional output data to include in the model response. Currently supported values are: + The unique ID of the custom tool call output item. - - `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). + - `status: :in_progress | :completed | :incomplete` - - `:"file_search_call.results"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `:"web_search_call.results"` + - `:in_progress` - - `:"web_search_call.action.sources"` + - `:completed` - - `:"message.input_image.image_url"` + - `:incomplete` - - `:"computer_call_output.output.image_url"` + - `created_by: String` - - `:"code_interpreter_call.outputs"` + The identifier of the actor that created the item. - - `:"reasoning.encrypted_content"` +### Example - - `:"message.output_text.logprobs"` +```ruby +require "openai" - - `input: String | BetaResponseInput` +openai = OpenAI::Client.new(api_key: "My API Key") - Text, image, or file inputs to the model, used to generate a response. +page = openai.beta.responses.input_items.list("response_id") - Learn more: +puts(page) +``` - - [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) +#### Response - - `String = String` +```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" +} +``` - A text input to the model, equivalent to a text input with the - `user` role. +## Domain Types - - `BetaResponseInput = Array[BetaResponseInputItem]` +### Beta Response Item List - A list of one or many input items to the model, containing - different content types. +- `class BetaResponseItemList` - - `class BetaEasyInputMessage` + A list of Response items. - 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. + - `data: Array[BetaResponseItem]` - - `content: String | BetaResponseInputMessageContentList` + A list of items used to generate this response. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `class BetaResponseInputMessageItem` - - `String = String` + - `id: String` - A text input to the model. + The unique ID of the message input. - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `content: BetaResponseInputMessageContentList` A list of one or many input items to the model, containing different content types. @@ -135302,54 +147835,22 @@ puts(beta_compacted_response) - `:explicit` - - `role: :user | :assistant | :system | :developer` + - `role: :user | :system | :developer` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The role of the message input. One of `user`, `system`, or `developer`. - `:user` - - `:assistant` - - `:system` - `:developer` - - `phase: :commentary` - - 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` - - `type: :message` - The type of the message input. Always `message`. + The type of the message input. Always set to `message`. - `:message` - - `class Message` - - 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 | :system | :developer` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `:user` - - - `:system` - - - `:developer` - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -135369,12 +147870,6 @@ puts(beta_compacted_response) - `:incomplete` - - `type: :message` - - The type of the message input. Always set to `message`. - - - `:message` - - `class BetaResponseOutputMessage` An output message from the model. @@ -135562,7 +148057,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :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 @@ -135570,6 +148065,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -135936,9 +148433,11 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput` + - `class BetaResponseComputerToolCallOutputItem` - The output of a computer tool call. + - `id: String` + + The unique ID of the computer call tool output. - `call_id: String` @@ -135963,19 +148462,29 @@ puts(beta_compacted_response) The URL of the screenshot image. + - `status: :completed | :incomplete | :failed | :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` - - `id: String` - - The ID of the computer tool call output. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The safety checks reported by the API that have been acknowledged by the developer. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: String` @@ -135997,15 +148506,9 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `status: :in_progress | :completed | :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` + - `created_by: String` - - `:incomplete` + The identifier of the actor that created the item. - `class BetaResponseFunctionWebSearch` @@ -136111,65 +148614,15 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall` + - `class BetaResponseFunctionToolCallItem` A tool call to run a function. See the [function calling guide](https://platform.openai.com/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: String` The unique ID of the function tool call. - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `caller_: Direct{ type} | Program{ caller_id, type}` - - The execution context that produced this tool call. - - - `class Direct` - - - `type: :direct` - - - `:direct` - - - `class Program` - - - `caller_id: String` - - The call ID of the program item that produced this tool call. - - - `type: :program` - - - `:program` - - - `namespace: String` - - The namespace of the function to run. - - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -136181,207 +148634,209 @@ puts(beta_compacted_response) - `:incomplete` - - `class FunctionCallOutput` + - `created_by: String` - The output of a function tool call. + The identifier of the actor that created the item. + + - `class BetaResponseFunctionToolCallOutputItem` + + - `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 | BetaResponseFunctionCallOutputItemList` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - Text, image, or file output of the function tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - `String = String` - A JSON string of the output of the function tool call. + A string of the output of the function call. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - An array of content outputs (text, image, file) for the function tool call. + Text, image, or file output of the function call. - - `class BetaResponseInputTextContent` + - `class BetaResponseInputText` 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`. + - `class BetaResponseInputImage` - - `:input_text` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class BetaResponseInputFile` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A file input to the model. - - `mode: :explicit` + - `status: :in_progress | :completed | :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` - - `class BetaResponseInputImageContent` + - `:completed` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:incomplete` - - `type: :input_image` + - `type: :function_call_output` - The type of the input item. Always `input_image`. + The type of the function tool call output. Always `function_call_output`. - - `:input_image` + - `:function_call_output` - - `detail: :low | :high | :auto | :original` + - `agent: Agent{ agent_name}` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `:low` + - `agent_name: String` - - `:high` + The canonical name of the agent that produced this item. - - `:auto` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:original` + The execution context that produced this tool call. - - `file_id: String` + - `class Direct` - The ID of the file to be sent to the model. + - `type: :direct` - - `image_url: String` + The caller type. Always `direct`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `:direct` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class 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. + - `caller_id: String` - - `mode: :explicit` + The call ID of the program item that produced this tool call. - The breakpoint mode. Always `explicit`. + - `type: :program` - - `:explicit` + The caller type. Always `program`. - - `class BetaResponseInputFileContent` + - `:program` - A file input to the model. + - `created_by: String` - - `type: :input_file` + The identifier of the actor that created the item. - The type of the input item. Always `input_file`. + - `class AgentMessage` - - `:input_file` + - `id: String` - - `detail: :auto | :low | :high` + The unique ID of the agent message. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `author: String` - - `:auto` + The sending agent identity. - - `:low` + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` - - `:high` + Encrypted content sent between agents. - - `file_data: String` + - `class BetaResponseInputText` - The base64-encoded data of the file to be sent to the model. + A text input to the model. - - `file_id: String` + - `class BetaResponseOutputText` - The ID of the file to be sent to the model. + A text output from the model. - - `file_url: String` + - `class Text` - The URL of the file to be sent to the model. + A text content. - - `filename: String` + - `text: String` - The name of the file to be sent to the model. + - `type: :text` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:text` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class SummaryText` - - `mode: :explicit` + A summary text from the model. - The breakpoint mode. Always `explicit`. + - `text: String` - - `:explicit` + A summary of the reasoning output from the model so far. - - `type: :function_call_output` + - `type: :summary_text` - The type of the function tool call output. Always `function_call_output`. + The type of the object. Always `summary_text`. - - `:function_call_output` + - `:summary_text` - - `id: String` + - `class ReasoningText` - The unique ID of the function tool call output. Populated when this item is returned via API. + Reasoning text from the model. - - `agent: Agent{ agent_name}` + - `text: String` - The agent that produced this item. + The reasoning text from the model. - - `agent_name: String` + - `type: :reasoning_text` - The canonical name of the agent that produced this item. + The type of the reasoning text. Always `reasoning_text`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:reasoning_text` - The execution context that produced this tool call. + - `class BetaResponseOutputRefusal` - - `class Direct` + A refusal from the model. - - `type: :direct` + - `class BetaResponseInputImage` - The caller type. Always `direct`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:direct` + - `class ComputerScreenshot` - - `class Program` + A screenshot of a computer. - - `caller_id: String` + - `detail: :low | :high | :auto | :original` - The call ID of the program item that produced this tool call. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: :program` + - `:low` - The caller type. Always `program`. + - `:high` - - `:program` + - `:auto` - - `status: :in_progress | :completed | :incomplete` + - `:original` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `file_id: String` - - `:in_progress` + The identifier of an uploaded file that contains the screenshot. - - `:completed` + - `image_url: String` - - `:incomplete` + The URL of the screenshot image. - - `class AgentMessage` + - `type: :computer_screenshot` - A message routed between agents. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `author: String` + - `:computer_screenshot` - The sending agent identity. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Plaintext, image, or encrypted content sent between agents. + - `mode: :explicit` - - `class BetaResponseInputTextContent` + The breakpoint mode. Always `explicit`. - A text input to the model. + - `:explicit` - - `class BetaResponseInputImageContent` + - `class BetaResponseInputFile` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A file input to the model. - `class EncryptedContent` @@ -136403,14 +148858,10 @@ puts(beta_compacted_response) - `type: :agent_message` - The item type. Always `agent_message`. + The type of the item. Always `agent_message`. - `:agent_message` - - `id: String` - - The unique ID of this agent message item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -136421,9 +148872,13 @@ puts(beta_compacted_response) - `class MultiAgentCall` + - `id: String` + + The unique ID of the multi-agent call item. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The multi-agent action that was executed. + The multi-agent action to execute. - `:spawn_agent` @@ -136439,7 +148894,7 @@ puts(beta_compacted_response) - `arguments: String` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `call_id: String` @@ -136447,14 +148902,10 @@ puts(beta_compacted_response) - `type: :multi_agent_call` - The item type. Always `multi_agent_call`. + The type of the multi-agent call. Always `multi_agent_call`. - `:multi_agent_call` - - `id: String` - - The unique ID of this multi-agent call. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -136465,6 +148916,10 @@ puts(beta_compacted_response) - `class MultiAgentCallOutput` + - `id: String` + + The unique ID of the multi-agent call output item. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` The multi-agent action that produced this result. @@ -136485,105 +148940,75 @@ puts(beta_compacted_response) The unique ID of the multi-agent call. - - `output: Array[Output{ text, type, annotations}]` + - `output: Array[BetaResponseOutputText]` 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: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - Citations associated with the text content. - - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - - `file_id: String` - - The ID of the file. - - - `filename: String` - - The filename of the file cited. - - - `index: Integer` - - The index of the file in the list of files. - - - `type: :file_citation` - - The citation type. Always `file_citation`. + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:file_citation` + The annotations of the text output. - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `text: String` - - `end_index: Integer` + The text output from the model. - The index of the last character of the citation in the message. + - `type: :output_text` - - `start_index: Integer` + The type of the output text. Always `output_text`. - The index of the first character of the citation in the message. + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `title: String` + - `type: :multi_agent_call_output` - The title of the cited resource. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `type: :url_citation` + - `:multi_agent_call_output` - The citation type. Always `url_citation`. + - `agent: Agent{ agent_name}` - - `:url_citation` + The agent that produced this item. - - `url: String` + - `agent_name: String` - The URL of the cited resource. + The canonical name of the agent that produced this item. - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `class BetaResponseToolSearchCall` - - `container_id: String` + - `id: String` - The ID of the container. + The unique ID of the tool search call item. - - `end_index: Integer` + - `arguments: untyped` - The index of the last character of the citation in the message. + Arguments used for the tool search call. - - `file_id: String` + - `call_id: String` - The ID of the container file. + The unique ID of the tool search call generated by the model. - - `filename: String` + - `execution: :server | :client` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `start_index: Integer` + - `:server` - The index of the first character of the citation in the message. + - `:client` - - `type: :container_file_citation` + - `status: :in_progress | :completed | :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: String` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `:tool_search_call` - `agent: Agent{ agent_name}` @@ -136593,29 +149018,15 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall` - - - `arguments: untyped` - - The arguments supplied to the tool search call. - - - `type: :tool_search_call` + - `created_by: String` - The item type. Always `tool_search_call`. + The identifier of the actor that created the item. - - `:tool_search_call` + - `class BetaResponseToolSearchOutputItem` - `id: String` - The unique ID of this tool search call. - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - `call_id: String` @@ -136631,7 +149042,7 @@ puts(beta_compacted_response) - `status: :in_progress | :completed | :incomplete` - The status of the tool search call. + The status of the tool search output item that was recorded. - `:in_progress` @@ -136639,11 +149050,9 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseToolSearchOutputItemParam` - - `tools: Array[BetaTool]` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool` @@ -136742,7 +149151,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -136752,7 +149161,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -136799,7 +149212,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -136809,7 +149222,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -137733,14 +150150,10 @@ puts(beta_compacted_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: String` - - The unique ID of this tool search output. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -137749,39 +150162,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` - - The unique ID of the tool search call generated by the model. + - `created_by: String` - - `execution: :server | :client` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `class AdditionalTools` - - `:server` + - `id: String` - - `:client` + The unique ID of the additional tools item. - - `status: :in_progress | :completed | :incomplete` + - `role: :unknown | :user | :assistant | 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `:in_progress` + - `:unknown` - - `:completed` + - `:user` - - `:incomplete` + - `:assistant` - - `class AdditionalTools` + - `:system` - - `role: :developer` + - `:critic` - The role that provided the additional tools. Only `developer` is supported. + - `:discriminator` - `:developer` + - `:tool` + - `tools: Array[BetaTool]` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `class BetaFunctionTool` @@ -137849,14 +150262,10 @@ puts(beta_compacted_response) - `type: :additional_tools` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `:additional_tools` - - `id: String` - - The unique ID of this additional tools item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -137934,13 +150343,85 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseCompactionItemParam` + - `class Program` + + - `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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :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: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: String` + + The unique ID of the compaction item. + - `encrypted_content: String` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: :compaction` @@ -137948,10 +150429,6 @@ puts(beta_compacted_response) - `:compaction` - - `id: String` - - The ID of the compaction item. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -137960,6 +150437,10 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. + - `created_by: String` + + The identifier of the actor that created the item. + - `class ImageGenerationCall` An image generation request made by the model. @@ -138165,41 +150646,79 @@ puts(beta_compacted_response) - `agent_name: String` - The canonical name of the agent that produced this item. + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseFunctionShellToolCall` + + 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: Action{ commands, max_output_length, timeout_ms}` + + The shell commands and limits that describe how to run the tool call. + + - `commands: Array[String]` + + - `max_output_length: Integer` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the commands. + + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` - - `status: :in_progress | :completed | :incomplete` + Represents the use of a local environment to perform shell actions. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `class BetaResponseLocalEnvironment` - - `:in_progress` + Represents the use of a local environment to perform shell actions. - - `:completed` + - `type: :local` - - `:incomplete` + The environment type. Always `local`. - - `class ShellCall` + - `:local` - A tool representing a request to execute one or more shell commands. + - `class BetaResponseContainerReference` - - `action: Action{ commands, max_output_length, timeout_ms}` + Represents a container created with /v1/containers. - The shell commands and limits that describe how to run the tool call. + - `container_id: String` - - `commands: Array[String]` + - `type: :container_reference` - Ordered shell commands for the execution environment to run. + The environment type. Always `container_reference`. - - `max_output_length: Integer` + - `:container_reference` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `status: :in_progress | :completed | :incomplete` - - `timeout_ms: Integer` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `:in_progress` - - `call_id: String` + - `:completed` - The unique ID of the shell tool call generated by the model. + - `:incomplete` - `type: :shell_call` @@ -138207,10 +150726,6 @@ puts(beta_compacted_response) - `:shell_call` - - `id: String` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -138227,8 +150742,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -138239,43 +150752,35 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `environment: BetaLocalEnvironment | BetaContainerReference` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment` - - - `class BetaContainerReference` - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: String` - - `:in_progress` + The ID of the entity that created this tool call. - - `:completed` + - `class BetaResponseFunctionShellToolCallOutput` - - `:incomplete` + The output of a shell tool call that was emitted. - - `class ShellCallOutput` + - `id: String` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: String` The unique ID of the shell tool call generated by the model. - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + - `max_output_length: Integer` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + + An array of shell call output contents - `outcome: Timeout{ type} | Exit{ exit_code, type}` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `class Timeout` @@ -138293,7 +150798,7 @@ puts(beta_compacted_response) - `exit_code: Integer` - The exit code returned by the shell process. + Exit code from the shell process. - `type: :exit` @@ -138303,21 +150808,31 @@ puts(beta_compacted_response) - `stderr: String` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: String` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: :shell_call_output` + - `created_by: String` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `:shell_call_output` + - `status: :in_progress | :completed | :incomplete` - - `id: String` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :shell_call_output` + + The type of the shell call output. Always `shell_call_output`. + + - `:shell_call_output` - `agent: Agent{ agent_name}` @@ -138335,8 +150850,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -138347,27 +150860,19 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `max_output_length: Integer` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call output. + - `created_by: String` - - `:in_progress` + The identifier of the actor that created the item. - - `:completed` + - `class BetaResponseApplyPatchToolCall` - - `:incomplete` + A tool call that applies file diffs by creating, deleting, or updating files. - - `class ApplyPatchCall` + - `id: String` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: String` @@ -138375,55 +150880,55 @@ puts(beta_compacted_response) - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `class CreateFile` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: String` - Unified diff content to apply when creating the file. + Diff to apply. - `path: String` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: :create_file` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `:create_file` - `class DeleteFile` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: String` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: :delete_file` - The operation type. Always `delete_file`. + Delete the specified file. - `:delete_file` - `class UpdateFile` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: String` - Unified diff content to apply to the existing file. + Diff to apply. - `path: String` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: :update_file` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `:update_file` @@ -138441,10 +150946,6 @@ puts(beta_compacted_response) - `:apply_patch_call` - - `id: String` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -138461,8 +150962,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -138473,13 +150972,19 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` - - `class ApplyPatchCallOutput` + - `created_by: String` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + 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` @@ -138499,10 +151004,6 @@ puts(beta_compacted_response) - `:apply_patch_call_output` - - `id: String` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -138519,8 +151020,6 @@ puts(beta_compacted_response) - `type: :direct` - The caller type. Always `direct`. - - `:direct` - `class Program` @@ -138531,13 +151030,15 @@ puts(beta_compacted_response) - `type: :program` - The caller type. Always `program`. - - `:program` + - `created_by: String` + + The ID of the entity that created this tool call output. + - `output: String` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. - `class McpListTools` @@ -138627,6 +151128,10 @@ puts(beta_compacted_response) 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. @@ -138641,10 +151146,6 @@ puts(beta_compacted_response) - `:mcp_approval_response` - - `id: String` - - The unique ID of the approval response - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -138718,238 +151219,294 @@ puts(beta_compacted_response) - `:failed` - - `class BetaResponseCustomToolCallOutput` + - `class BetaResponseCustomToolCallItem` + + A call to a custom tool created by the model. + + - `id: String` + + The unique ID of the custom tool call item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseCustomToolCallOutputItem` The output of a custom tool call from your code, being sent back to the model. - - `call_id: String` + - `id: String` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the custom tool call output item. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `status: :in_progress | :completed | :incomplete` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `String = String` + - `:in_progress` - A string of the output of the custom tool call. + - `:completed` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:incomplete` - Text, image, or file output of the custom tool call. + - `created_by: String` - - `class BetaResponseInputText` + The identifier of the actor that created the item. - A text input to the model. + - `first_id: String` - - `class BetaResponseInputImage` + The ID of the first item in the list. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `has_more: bool` - - `class BetaResponseInputFile` + Whether there are more items available. - A file input to the model. + - `last_id: String` - - `type: :custom_tool_call_output` + The ID of the last item in the list. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `object: :list` - - `:custom_tool_call_output` + The type of object returned, must be `list`. - - `id: String` + - `:list` - The unique ID of the custom tool call output in the OpenAI platform. +# Input Tokens - - `agent: Agent{ agent_name}` +## Get input token counts - The agent that produced this item. +`beta.responses.input_tokens.count(**kwargs) -> InputTokenCountResponse` - - `agent_name: String` +**post** `/responses/input_tokens?beta=true` - The canonical name of the agent that produced this item. +Returns input token counts of the request. - - `caller_: Direct{ type} | Program{ caller_id, type}` +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - The execution context that produced this tool call. +### Parameters - - `class Direct` +- `conversation: String | BetaResponseConversationParam` - - `type: :direct` + 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 caller type. Always `direct`. + - `String = String` - - `:direct` + The unique ID of the conversation. - - `class Program` + - `class BetaResponseConversationParam` - - `caller_id: String` + The conversation that this response belongs to. - The call ID of the program item that produced this tool call. + - `id: String` - - `type: :program` + The unique ID of the conversation. - The caller type. Always `program`. +- `input: String | Array[BetaResponseInputItem]` - - `:program` + Text, image, or file inputs to the model, used to generate a response - - `class BetaResponseCustomToolCall` + - `String = String` - A call to a custom tool created by the model. + A text input to the model, equivalent to a text input with the `user` role. - - `call_id: String` + - `UnionMember1 = Array[BetaResponseInputItem]` - 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` + - `class BetaEasyInputMessage` - 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 | 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` + - `String = String` - The type of the custom tool call. Always `custom_tool_call`. + A text input to the model. - - `:custom_tool_call` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `id: 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. + - `class BetaResponseInputText` - - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + The type of the input item. Always `input_text`. - The execution context that produced this tool call. + - `:input_text` - - `class Direct` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` - - `class Program` + The breakpoint mode. Always `explicit`. - - `caller_id: String` + - `:explicit` - The call ID of the program item that produced this tool call. + - `class BetaResponseInputImage` - - `type: :program` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `:program` + - `detail: :low | :high | :auto | :original` - - `namespace: 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` - - `class CompactionTrigger` + - `:high` - Compacts the current context. Must be the final input item. + - `:auto` - - `type: :compaction_trigger` + - `:original` - The type of the item. Always `compaction_trigger`. + - `type: :input_image` - - `:compaction_trigger` + The type of the input item. Always `input_image`. - - `agent: Agent{ agent_name}` + - `:input_image` - The agent that produced this item. + - `file_id: String` - - `agent_name: String` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `image_url: String` - - `class ItemReference` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - An internal identifier for an item to reference. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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 item to reference. + - `mode: :explicit` - - `agent: Agent{ agent_name}` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `:explicit` - - `agent_name: String` + - `class BetaResponseInputFile` - The canonical name of the agent that produced this item. + A file input to the model. - - `type: :item_reference` + - `type: :input_file` - The type of item to reference. Always `item_reference`. + The type of the input item. Always `input_file`. - - `:item_reference` + - `:input_file` - - `class Program` + - `detail: :auto | :low | :high` - - `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 this program item. + - `:auto` - - `call_id: String` + - `:low` - The stable call ID of the program item. + - `:high` - - `code: String` + - `file_data: String` - The JavaScript source executed by programmatic tool calling. + The content of the file to be sent to the model. - - `fingerprint: String` + - `file_id: String` - Opaque program replay fingerprint that must be round-tripped. + The ID of the file to be sent to the model. - - `type: :program` + - `file_url: String` - The item type. Always `program`. + The URL of the file to be sent to the model. - - `:program` + - `filename: String` - - `agent: Agent{ agent_name}` + The name of the file to be sent to the model. - The agent that produced this item. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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` - - `class ProgramOutput` + The breakpoint mode. Always `explicit`. - - `id: String` + - `:explicit` - The unique ID of this program output item. + - `role: :user | :assistant | :system | :developer` - - `call_id: String` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The call ID of the program item. + - `:user` - - `result: String` + - `:assistant` - The result produced by the program item. + - `:system` - - `status: :completed | :incomplete` + - `:developer` - The terminal status of the program output. + - `phase: :commentary | :final_answer` - - `:completed` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `:incomplete` + - `:commentary` - - `type: :program_output` + - `:final_answer` - The item type. Always `program_output`. + - `type: :message` - - `:program_output` + The type of the message input. Always `message`. + + - `:message` + + - `class Message` + + 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 | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` - `agent: Agent{ agent_name}` @@ -138959,2560 +151516,2514 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `instructions: String` + - `status: :in_progress | :completed | :incomplete` - A system (or developer) message inserted into the model's context. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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. + - `:in_progress` - - `max_output_tokens: Integer` + - `:completed` - 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). + - `:incomplete` - - `max_tool_calls: Integer` + - `type: :message` - 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 message input. Always set to `message`. - - `metadata: Hash[Symbol, String]` + - `: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. + - `class BetaResponseOutputMessage` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + An output message from the model. - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` + - `id: 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 unique ID of the output message. - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - 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 content of the output message. - - `:"gpt-5.6-sol"` + - `class BetaResponseOutputText` - - `:"gpt-5.6-terra"` + A text output from the model. - - `:"gpt-5.6-luna"` + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - `:"gpt-5.4"` + The annotations of the text output. - - `:"gpt-5.4-mini"` + - `class FileCitation` - - `:"gpt-5.4-nano"` + A citation to a file. - - `:"gpt-5.4-mini-2026-03-17"` + - `file_id: String` - - `:"gpt-5.4-nano-2026-03-17"` + The ID of the file. - - `:"gpt-5.3-chat-latest"` + - `filename: String` - - `:"gpt-5.2"` + The filename of the file cited. - - `:"gpt-5.2-2025-12-11"` + - `index: Integer` - - `:"gpt-5.2-chat-latest"` + The index of the file in the list of files. - - `:"gpt-5.2-pro"` + - `type: :file_citation` - - `:"gpt-5.2-pro-2025-12-11"` + The type of the file citation. Always `file_citation`. - - `:"gpt-5.1"` + - `:file_citation` - - `:"gpt-5.1-2025-11-13"` + - `class URLCitation` - - `:"gpt-5.1-codex"` + A citation for a web resource used to generate a model response. - - `:"gpt-5.1-mini"` + - `end_index: Integer` - - `:"gpt-5.1-chat-latest"` + The index of the last character of the URL citation in the message. - - `:"gpt-5"` + - `start_index: Integer` - - `:"gpt-5-mini"` + The index of the first character of the URL citation in the message. - - `:"gpt-5-nano"` + - `title: String` - - `:"gpt-5-2025-08-07"` + The title of the web resource. - - `:"gpt-5-mini-2025-08-07"` + - `type: :url_citation` - - `:"gpt-5-nano-2025-08-07"` + The type of the URL citation. Always `url_citation`. - - `:"gpt-5-chat-latest"` + - `:url_citation` - - `:"gpt-4.1"` + - `url: String` - - `:"gpt-4.1-mini"` + The URL of the web resource. - - `:"gpt-4.1-nano"` + - `class ContainerFileCitation` - - `:"gpt-4.1-2025-04-14"` + A citation for a container file used to generate a model response. - - `:"gpt-4.1-mini-2025-04-14"` + - `container_id: String` - - `:"gpt-4.1-nano-2025-04-14"` + The ID of the container file. - - `:"o4-mini"` + - `end_index: Integer` - - `:"o4-mini-2025-04-16"` + The index of the last character of the container file citation in the message. - - `:o3` + - `file_id: String` - - `:"o3-2025-04-16"` + The ID of the file. - - `:"o3-mini"` + - `filename: String` - - `:"o3-mini-2025-01-31"` + The filename of the container file cited. - - `:o1` + - `start_index: Integer` - - `:"o1-2024-12-17"` + The index of the first character of the container file citation in the message. - - `:"o1-preview"` + - `type: :container_file_citation` - - `:"o1-preview-2024-09-12"` + The type of the container file citation. Always `container_file_citation`. - - `:"o1-mini"` + - `:container_file_citation` - - `:"o1-mini-2024-09-12"` + - `class FilePath` - - `:"gpt-4o"` + A path to a file. - - `:"gpt-4o-2024-11-20"` + - `file_id: String` - - `:"gpt-4o-2024-08-06"` + The ID of the file. - - `:"gpt-4o-2024-05-13"` + - `index: Integer` - - `:"gpt-4o-audio-preview"` + The index of the file in the list of files. - - `:"gpt-4o-audio-preview-2024-10-01"` + - `type: :file_path` - - `:"gpt-4o-audio-preview-2024-12-17"` + The type of the file path. Always `file_path`. - - `:"gpt-4o-audio-preview-2025-06-03"` + - `:file_path` - - `:"gpt-4o-mini-audio-preview"` + - `text: String` - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + The text output from the model. - - `:"gpt-4o-search-preview"` + - `type: :output_text` - - `:"gpt-4o-mini-search-preview"` + The type of the output text. Always `output_text`. - - `:"gpt-4o-search-preview-2025-03-11"` + - `:output_text` - - `:"gpt-4o-mini-search-preview-2025-03-11"` + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - `:"chatgpt-4o-latest"` + - `token: String` - - `:"codex-mini-latest"` + - `bytes: Array[Integer]` - - `:"gpt-4o-mini"` + - `logprob: Float` - - `:"gpt-4o-mini-2024-07-18"` + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - `:"gpt-4-turbo"` + - `token: String` - - `:"gpt-4-turbo-2024-04-09"` + - `bytes: Array[Integer]` - - `:"gpt-4-0125-preview"` + - `logprob: Float` - - `:"gpt-4-turbo-preview"` + - `class BetaResponseOutputRefusal` - - `:"gpt-4-1106-preview"` + A refusal from the model. - - `:"gpt-4-vision-preview"` + - `refusal: String` - - `:"gpt-4"` + The refusal explanation from the model. - - `:"gpt-4-0314"` + - `type: :refusal` - - `:"gpt-4-0613"` + The type of the refusal. Always `refusal`. - - `:"gpt-4-32k"` + - `:refusal` - - `:"gpt-4-32k-0314"` + - `role: :assistant` - - `:"gpt-4-32k-0613"` + The role of the output message. Always `assistant`. - - `:"gpt-3.5-turbo"` + - `:assistant` - - `:"gpt-3.5-turbo-16k"` + - `status: :in_progress | :completed | :incomplete` - - `:"gpt-3.5-turbo-0301"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `:"gpt-3.5-turbo-0613"` + - `:in_progress` - - `:"gpt-3.5-turbo-1106"` + - `:completed` - - `:"gpt-3.5-turbo-0125"` + - `:incomplete` - - `:"gpt-3.5-turbo-16k-0613"` + - `type: :message` - - `:"o1-pro"` + The type of the output message. Always `message`. - - `:"o1-pro-2025-03-19"` + - `:message` - - `:"o3-pro"` + - `agent: Agent{ agent_name}` - - `:"o3-pro-2025-06-10"` + The agent that produced this item. - - `:"o3-deep-research"` + - `agent_name: String` - - `:"o3-deep-research-2025-06-26"` + The canonical name of the agent that produced this item. - - `:"o4-mini-deep-research"` + - `phase: :commentary | :final_answer` - - `:"o4-mini-deep-research-2025-06-26"` + 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. - - `:"computer-use-preview"` + - `:commentary` - - `:"computer-use-preview-2025-03-11"` + - `:final_answer` - - `:"gpt-5-codex"` + - `class BetaResponseFileSearchToolCall` - - `:"gpt-5-pro"` + 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. - - `:"gpt-5-pro-2025-10-06"` + - `id: String` - - `:"gpt-5.1-codex-max"` + The unique ID of the file search tool call. - - `String = String` + - `queries: Array[String]` - - `moderation: Moderation{ model, policy}` + The queries used to search for files. - Configuration for running moderation on the input and output of this response. + - `status: :in_progress | :searching | :completed | 2 more` - - `model: String` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `:in_progress` - - `policy: Policy{ input, output}` + - `:searching` - The policy to apply to moderated response input and output. + - `:completed` - - `input: Input{ mode}` + - `:incomplete` - The moderation policy for the response input. + - `:failed` - - `mode: :score | :block` + - `type: :file_search_call` - - `:score` + The type of the file search tool call. Always `file_search_call`. - - `:block` + - `:file_search_call` - - `output: Output{ mode}` + - `agent: Agent{ agent_name}` - The moderation policy for the response output. + The agent that produced this item. - - `mode: :score | :block` + - `agent_name: String` - - `:score` + The canonical name of the agent that produced this item. - - `:block` + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` - - `multi_agent: MultiAgent{ enabled, max_concurrent_subagents}` + The results of the file search tool call. - Configuration for server-hosted multi-agent execution. + - `attributes: Hash[Symbol, String | Float | bool]` - - `enabled: bool` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - Whether to enable server-hosted multi-agent execution for this response. + - `String = String` - - `max_concurrent_subagents: Integer` + - `Float = Float` - `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. + - `UnionMember2 = bool` - - `parallel_tool_calls: bool` + - `file_id: String` - Whether to allow the model to run tool calls in parallel. + The unique ID of the file. - - `previous_response_id: String` + - `filename: 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. - - `prompt: BetaResponsePrompt` + - `score: Float` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The relevance score of the file - a value between 0 and 1. + + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + 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 identifier of the prompt template to use. + The unique ID of the computer call. - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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. + An identifier used when responding to the tool call with output. - - `String = String` + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` - - `class BetaResponseInputText` + The pending safety checks for the computer call. - A text input to the model. + - `id: String` - - `class BetaResponseInputImage` + The ID of the pending safety check. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `code: String` - - `class BetaResponseInputFile` + The type of the pending safety check. - A file input to the model. + - `message: String` - - `version: String` + Details about the pending safety check. - Optional version of the prompt template. + - `status: :in_progress | :completed | :incomplete` - - `prompt_cache_key: String` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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). + - `:in_progress` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `:completed` - 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. + - `:incomplete` - - `mode: :implicit | :explicit` + - `type: :computer_call` - 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 type of the computer call. Always `computer_call`. - - `:implicit` + - `:computer_call` - - `:explicit` + - `action: BetaComputerAction` - - `ttl: :"30m"` + A click action. - 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. + - `class Click` - - `:"30m"` + A click action. - - `prompt_cache_retention: :in_memory | :"24h"` + - `button: :left | :right | :wheel | 2 more` - Deprecated. Use `prompt_cache_options.ttl` instead. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - 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. + - `:left` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `:right` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `:wheel` - - `:in_memory` + - `:back` - - `:"24h"` + - `:forward` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `type: :click` - **gpt-5 and o-series models only** + Specifies the event type. For a click action, this property is always `click`. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `:click` - - `context: :auto | :current_turn | :all_turns` + - `x: Integer` - 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 x-coordinate where the click occurred. - - `:auto` + - `y_: Integer` - - `:current_turn` + The y-coordinate where the click occurred. - - `:all_turns` + - `keys: Array[String]` - - `effort: :none | :minimal | :low | 4 more` + The keys being held while clicking. - 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. + - `class DoubleClick` - - `:none` + A double click action. - - `:minimal` + - `keys: Array[String]` - - `:low` + The keys being held while double-clicking. - - `:medium` + - `type: :double_click` - - `:high` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `:xhigh` + - `:double_click` - - `:max` + - `x: Integer` - - `generate_summary: :auto | :concise | :detailed` + The x-coordinate where the double click occurred. - **Deprecated:** use `summary` instead. + - `y_: Integer` - 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 y-coordinate where the double click occurred. - - `:auto` + - `class Drag` - - `:concise` + A drag action. - - `:detailed` + - `path: Array[Path{ x, y_}]` - - `mode: String | :standard | :pro` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Controls the reasoning execution mode for the request. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - When returned on a response, this is the effective execution mode. + - `x: Integer` - - `String = String` + The x-coordinate. - - `Mode = :standard | :pro` + - `y_: Integer` - Controls the reasoning execution mode for the request. + The y-coordinate. - When returned on a response, this is the effective execution mode. + - `type: :drag` - - `:standard` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `:pro` + - `:drag` - - `summary: :auto | :concise | :detailed` + - `keys: Array[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 keys being held while dragging the mouse. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `class Keypress` - - `:auto` + A collection of keypresses the model would like to perform. - - `:concise` + - `keys: Array[String]` - - `:detailed` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `safety_identifier: String` + - `type: :keypress` - 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). + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `service_tier: :auto | :default | :flex | 2 more` + - `:keypress` - Specifies the processing type used for serving the request. + - `class Move` - - 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 mouse move action. - 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: :move` - - `:auto` + Specifies the event type. For a move action, this property is always set to `move`. - - `:default` + - `:move` - - `:flex` + - `x: Integer` - - `:scale` + The x-coordinate to move to. - - `:priority` + - `y_: Integer` - - `store: bool` + The y-coordinate to move to. - Whether to store the generated model response for later retrieval via - API. + - `keys: Array[String]` - - `stream: bool` + The keys being held while moving the mouse. - 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. + - `class Screenshot` - - `stream_options: StreamOptions{ include_obfuscation}` + A screenshot action. - Options for streaming responses. Only set this when you set `stream: true`. + - `type: :screenshot` - - `include_obfuscation: bool` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - 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. + - `:screenshot` - - `temperature: Float` + - `class Scroll` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + A scroll action. - - `text: BetaResponseTextConfig` + - `scroll_x: Integer` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The horizontal scroll distance. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `scroll_y: Integer` - - `format_: BetaResponseFormatTextConfig` + The vertical scroll distance. - An object specifying the format that the model must output. + - `type: :scroll` - 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). + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` - The default format is `{ "type": "text" }` with no additional options. + The y-coordinate where the scroll occurred. - **Not recommended for gpt-4o and newer models:** + - `keys: Array[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 keys being held while scrolling. - - `class Text` + - `class Type` - Default response format. Used to generate text responses. + An action to type in text. - - `type: :text` + - `text: String` - The type of response format being defined. Always `text`. + The text to type. - - `:text` + - `type: :type` - - `class BetaResponseFormatTextJSONSchemaConfig` + Specifies the event type. For a type action, this property is always set to `type`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `:type` - - `name: String` + - `class Wait` - 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 wait action. - - `schema: Hash[Symbol, untyped]` + - `type: :wait` - 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 event type. For a wait action, this property is always set to `wait`. - - `type: :json_schema` + - `:wait` - The type of response format being defined. Always `json_schema`. + - `actions: BetaComputerActionList` - - `:json_schema` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `description: String` + - `class Click` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A click action. - - `strict: bool` + - `class DoubleClick` - 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). + A double click action. - - `class JSONObject` + - `class Drag` - 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 drag action. - - `type: :json_object` + - `class Keypress` - The type of response format being defined. Always `json_object`. + A collection of keypresses the model would like to perform. - - `:json_object` + - `class Move` - - `verbosity: :low | :medium | :high` + A mouse move 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`. + - `class Screenshot` - - `:low` + A screenshot action. - - `:medium` + - `class Scroll` - - `:high` + A scroll action. - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `class Type` - 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. + An action to type in text. - - `BetaToolChoiceOptions = :none | :auto | :required` + - `class Wait` - Controls which (if any) tool is called by the model. + A wait action. - `none` means the model will not call any tool and instead generates a message. + - `agent: Agent{ agent_name}` - `auto` means the model can pick between generating a message or calling one or - more tools. + The agent that produced this item. - `required` means the model must call one or more tools. + - `agent_name: String` - - `:none` + The canonical name of the agent that produced this item. - - `:auto` + - `class ComputerCallOutput` - - `:required` + The output of a computer tool call. - - `class BetaToolChoiceAllowed` + - `call_id: String` - Constrains the tools available to the model to a pre-defined set. + The ID of the computer tool call that produced the output. - - `mode: :auto | :required` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Constrains the tools available to the model to a pre-defined set. + A computer screenshot image used with the computer use tool. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `type: :computer_screenshot` - `required` requires the model to call one or more of the allowed tools. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `:auto` + - `:computer_screenshot` - - `:required` + - `file_id: String` - - `tools: Array[Hash[Symbol, untyped]]` + The identifier of an uploaded file that contains the screenshot. - A list of tool definitions that the model should be allowed to call. + - `image_url: String` - For the Responses API, the list of tool definitions might look like: + The URL of the screenshot image. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `type: :computer_call_output` - - `type: :allowed_tools` + The type of the computer tool call output. Always `computer_call_output`. - Allowed tool configuration type. Always `allowed_tools`. + - `:computer_call_output` - - `:allowed_tools` + - `id: String` - - `class BetaToolChoiceTypes` + The ID of the computer tool call output. - 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). + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - - `type: :file_search | :web_search_preview | :computer | 5 more` + The safety checks reported by the API that have been acknowledged by the developer. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `id: String` - Allowed values are: + The ID of the pending safety check. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `code: String` - - `:file_search` + The type of the pending safety check. - - `:web_search_preview` + - `message: String` - - `:computer` + Details about the pending safety check. - - `:computer_use_preview` + - `agent: Agent{ agent_name}` - - `:computer_use` + The agent that produced this item. - - `:web_search_preview_2025_03_11` + - `agent_name: String` - - `:image_generation` + The canonical name of the agent that produced this item. - - `:code_interpreter` + - `status: :in_progress | :completed | :incomplete` - - `class BetaToolChoiceFunction` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - Use this option to force the model to call a specific function. + - `:in_progress` - - `name: String` + - `:completed` - The name of the function to call. + - `:incomplete` - - `type: :function` + - `class BetaResponseFunctionWebSearch` - For function calling, the type is always `function`. + 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. - - `:function` + - `id: String` - - `class BetaToolChoiceMcp` + The unique ID of the web search tool call. - Use this option to force the model to call a specific tool on a remote MCP server. + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ 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). - The label of the MCP server to use. + - `class Search` - - `type: :mcp` + Action type "search" - Performs a web search query. - For MCP tools, the type is always `mcp`. + - `type: :search` - - `:mcp` + The action type. - - `name: String` + - `:search` - The name of the tool to call on the server. + - `queries: Array[String]` - - `class BetaToolChoiceCustom` + The search queries. - Use this option to force the model to call a specific custom tool. + - `query: String` - - `name: String` + The search query. - The name of the custom tool to call. + - `sources: Array[Source{ type, url}]` - - `type: :custom` + The sources used in the search. - For custom tool calling, the type is always `custom`. + - `type: :url` - - `:custom` + The type of source. Always `url`. - - `class BetaSpecificProgrammaticToolCallingParam` + - `:url` - - `type: :programmatic_tool_calling` + - `url: String` - The tool to call. Always `programmatic_tool_calling`. + The URL of the source. - - `:programmatic_tool_calling` + - `class OpenPage` - - `class BetaToolChoiceApplyPatch` + Action type "open_page" - Opens a specific URL from search results. - Forces the model to call the apply_patch tool when executing a tool call. + - `type: :open_page` - - `type: :apply_patch` + The action type. - The tool to call. Always `apply_patch`. + - `:open_page` - - `:apply_patch` + - `url: String` - - `class BetaToolChoiceShell` + The URL opened by the model. - Forces the model to call the shell tool when a tool call is required. + - `class FindInPage` - - `type: :shell` + Action type "find_in_page": Searches for a pattern within a loaded page. - The tool to call. Always `shell`. + - `pattern: String` - - `:shell` + The pattern or text to search for within the page. - - `tools: Array[BetaTool]` + - `type: :find_in_page` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The action type. - We support the following categories of tools: + - `:find_in_page` - - **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. + - `url: String` - - `class BetaFunctionTool` + The URL of the page searched for the pattern. - 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). + - `status: :in_progress | :searching | :completed | :failed` - - `class BetaFileSearchTool` + The status of the web search 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). + - `:in_progress` - - `class BetaComputerTool` + - `:searching` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:completed` - - `class BetaComputerUsePreviewTool` + - `:failed` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :web_search_call` - - `class BetaWebSearchTool` + The type of the web search tool call. Always `web_search_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). + - `:web_search_call` - - `class Mcp` + - `agent: Agent{ 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. - - `class CodeInterpreter` + - `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. - - `class ProgrammaticToolCalling` + - `class BetaResponseFunctionToolCall` - - `class ImageGeneration` + 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 that generates images using the GPT image models. + - `arguments: String` - - `class LocalShell` + 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` - - `class BetaFunctionShellTool` + The unique ID of the function tool call generated by the model. - A tool that allows the model to execute shell commands. + - `name: String` - - `class BetaCustomTool` + The name of the function to run. - 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: :function_call` - - `class BetaNamespaceTool` + The type of the function tool call. Always `function_call`. - Groups function/custom tools under a shared namespace. + - `:function_call` - - `class BetaToolSearchTool` + - `id: String` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the function tool call. - - `class BetaWebSearchPreviewTool` + - `agent: Agent{ 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. - - `class BetaApplyPatchTool` + - `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. - - `top_logprobs: Integer` + - `caller_: Direct{ type} | Program{ caller_id, type}` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The execution context that produced this tool call. - - `top_p: Float` + - `class 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. + - `type: :direct` - We generally recommend altering this or `temperature` but not both. + - `:direct` - - `truncation: :auto | :disabled` + - `class Program` - The truncation strategy to use for the model response. + - `caller_id: 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 call ID of the program item that produced this tool call. - - `:auto` + - `type: :program` - - `:disabled` + - `:program` - - `user: String` + - `namespace: 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 namespace of the function to run. - - `class ResponseInject` + - `status: :in_progress | :completed | :incomplete` - 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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `input: Array[BetaResponseInputItem]` + - `:in_progress` - Input items to inject into the active response. + - `:completed` - - `class BetaEasyInputMessage` + - `:incomplete` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `class FunctionCallOutput` - - `class Message` + The output of a function 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. + - `call_id: String` - - `class BetaResponseOutputMessage` + The unique ID of the function tool call generated by the model. - An output message from the model. + - `output: String | BetaResponseFunctionCallOutputItemList` - - `class BetaResponseFileSearchToolCall` + Text, image, or file output of the function tool call. - 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. + - `String = String` - - `class BetaResponseComputerToolCall` + A JSON string of the output of the function tool call. - 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. + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - - `class ComputerCallOutput` + An array of content outputs (text, image, file) for the function tool call. - The output of a computer tool call. + - `class BetaResponseInputTextContent` - - `class BetaResponseFunctionWebSearch` + A text input to the model. - 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. + - `text: String` - - `class BetaResponseFunctionToolCall` + The text input 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. + - `type: :input_text` - - `class FunctionCallOutput` + The type of the input item. Always `input_text`. - The output of a function tool call. + - `:input_text` - - `class AgentMessage` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - A message routed between agents. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class MultiAgentCall` + - `mode: :explicit` - - `class MultiAgentCallOutput` + The breakpoint mode. Always `explicit`. - - `class ToolSearchCall` + - `:explicit` - - `class BetaResponseToolSearchOutputItemParam` + - `class BetaResponseInputImageContent` - - `class AdditionalTools` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class BetaResponseReasoningItem` + - `type: :input_image` - 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 input item. Always `input_image`. - - `class BetaResponseCompactionItemParam` + - `:input_image` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `detail: :low | :high | :auto | :original` - - `class ImageGenerationCall` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - An image generation request made by the model. + - `:low` - - `class BetaResponseCodeInterpreterToolCall` + - `:high` - A tool call to run code. + - `:auto` - - `class LocalShellCall` + - `:original` - A tool call to run a command on the local shell. + - `file_id: String` - - `class LocalShellCallOutput` + The ID of the file to be sent to the model. - The output of a local shell tool call. + - `image_url: String` - - `class ShellCall` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - A tool representing a request to execute one or more shell commands. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class ShellCallOutput` + Marks the exact end of a reusable 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 streamed output items emitted by a shell tool call. + - `mode: :explicit` - - `class ApplyPatchCall` + The breakpoint mode. Always `explicit`. - A tool call representing a request to create, delete, or update files using diff patches. + - `:explicit` - - `class ApplyPatchCallOutput` + - `class BetaResponseInputFileContent` - The streamed output emitted by an apply patch tool call. + A file input to the model. - - `class McpListTools` + - `type: :input_file` - A list of tools available on an MCP server. + The type of the input item. Always `input_file`. - - `class McpApprovalRequest` + - `:input_file` - A request for human approval of a tool invocation. + - `detail: :auto | :low | :high` - - `class McpApprovalResponse` + 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 response to an MCP approval request. + - `:auto` - - `class McpCall` + - `:low` - An invocation of a tool on an MCP server. + - `:high` - - `class BetaResponseCustomToolCallOutput` + - `file_data: String` - The output of a custom tool call from your code, being sent back to the model. + The base64-encoded data of the file to be sent to the model. - - `class BetaResponseCustomToolCall` + - `file_id: String` - A call to a custom tool created by the model. + The ID of the file to be sent to the model. - - `class CompactionTrigger` + - `file_url: String` - Compacts the current context. Must be the final input item. + The URL of the file to be sent to the model. - - `class ItemReference` + - `filename: String` - An internal identifier for an item to reference. + The name of the file to be sent to the model. - - `class Program` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `class ProgramOutput` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `response_id: String` + - `mode: :explicit` - The ID of the active response that should receive the input. + The breakpoint mode. Always `explicit`. - - `type: :"response.inject"` + - `:explicit` - The event discriminator. Always `response.inject`. + - `type: :function_call_output` - - `:"response.inject"` + The type of the function tool call output. Always `function_call_output`. -### Beta Responses Server Event + - `:function_call_output` -- `BetaResponsesServerEvent = BetaResponseAudioDeltaEvent | BetaResponseAudioDoneEvent | BetaResponseAudioTranscriptDeltaEvent | 52 more` + - `id: String` - Server events emitted by the Responses WebSocket server. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `class BetaResponseAudioDeltaEvent` + - `agent: Agent{ agent_name}` - Emitted when there is a partial audio response. + The agent that produced this item. - - `delta: String` + - `agent_name: String` - A chunk of Base64 encoded response audio bytes. + The canonical name of the agent that produced this item. - - `sequence_number: Integer` + - `caller_: Direct{ type} | Program{ caller_id, type}` - A sequence number for this chunk of the stream response. + The execution context that produced this tool call. - - `type: :"response.audio.delta"` + - `class Direct` - The type of the event. Always `response.audio.delta`. + - `type: :direct` - - `:"response.audio.delta"` + The caller type. Always `direct`. - - `agent: Agent{ agent_name}` + - `:direct` - The agent that owns this multi-agent streaming event. + - `class Program` - - `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. - - `class BetaResponseAudioDoneEvent` + - `type: :program` - Emitted when the audio response is complete. + The caller type. Always `program`. - - `sequence_number: Integer` + - `:program` - The sequence number of the delta. + - `status: :in_progress | :completed | :incomplete` - - `type: :"response.audio.done"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The type of the event. Always `response.audio.done`. + - `:in_progress` - - `:"response.audio.done"` + - `:completed` - - `agent: Agent{ agent_name}` + - `:incomplete` - The agent that owns this multi-agent streaming event. + - `class AgentMessage` - - `agent_name: String` + A message routed between agents. - The canonical name of the agent that produced this item. + - `author: String` - - `class BetaResponseAudioTranscriptDeltaEvent` + The sending agent identity. - Emitted when there is a partial transcript of audio. + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `delta: String` + Plaintext, image, or encrypted content sent between agents. - The partial transcript of the audio response. + - `class BetaResponseInputTextContent` - - `sequence_number: Integer` + A text input to the model. - The sequence number of this event. + - `class BetaResponseInputImageContent` - - `type: :"response.audio.transcript.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.audio.transcript.delta`. + - `class EncryptedContent` - - `:"response.audio.transcript.delta"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `agent: Agent{ agent_name}` + - `encrypted_content: String` - The agent that owns this multi-agent streaming event. + Opaque encrypted content. - - `agent_name: String` + - `type: :encrypted_content` - The canonical name of the agent that produced this item. + The type of the input item. Always `encrypted_content`. - - `class BetaResponseAudioTranscriptDoneEvent` + - `:encrypted_content` - Emitted when the full audio transcript is completed. + - `recipient: String` - - `sequence_number: Integer` + The destination agent identity. - The sequence number of this event. + - `type: :agent_message` - - `type: :"response.audio.transcript.done"` + The item type. Always `agent_message`. - The type of the event. Always `response.audio.transcript.done`. + - `:agent_message` - - `:"response.audio.transcript.done"` + - `id: String` + + The unique ID of this agent message item. - `agent: Agent{ 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. - - `class BetaResponseCodeInterpreterCallCodeDeltaEvent` + - `class MultiAgentCall` - Emitted when a partial code snippet is streamed by the code interpreter. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `delta: String` + The multi-agent action that was executed. - The partial code snippet being streamed by the code interpreter. + - `:spawn_agent` - - `item_id: String` + - `:interrupt_agent` - The unique identifier of the code interpreter tool call item. + - `:list_agents` - - `output_index: Integer` + - `:send_message` - The index of the output item in the response for which the code is being streamed. + - `:followup_task` - - `sequence_number: Integer` + - `:wait_agent` - The sequence number of this event, used to order streaming events. + - `arguments: String` - - `type: :"response.code_interpreter_call_code.delta"` + The action arguments as a JSON string. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `call_id: String` - - `:"response.code_interpreter_call_code.delta"` + The unique ID linking this call to its output. + + - `type: :multi_agent_call` + + The item type. Always `multi_agent_call`. + + - `:multi_agent_call` + + - `id: String` + + The unique ID of this multi-agent call. - `agent: Agent{ 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. - - `class BetaResponseCodeInterpreterCallCodeDoneEvent` + - `class MultiAgentCallOutput` - Emitted when the code snippet is finalized by the code interpreter. + - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - `code: String` + The multi-agent action that produced this result. - The final code snippet output by the code interpreter. + - `:spawn_agent` - - `item_id: String` + - `:interrupt_agent` - The unique identifier of the code interpreter tool call item. + - `:list_agents` - - `output_index: Integer` + - `:send_message` - The index of the output item in the response for which the code is finalized. + - `:followup_task` - - `sequence_number: Integer` + - `:wait_agent` - The sequence number of this event, used to order streaming events. + - `call_id: String` - - `type: :"response.code_interpreter_call_code.done"` + The unique ID of the multi-agent call. - The type of the event. Always `response.code_interpreter_call_code.done`. + - `output: Array[Output{ text, type, annotations}]` - - `:"response.code_interpreter_call_code.done"` + Text output returned by the multi-agent action. - - `agent: Agent{ agent_name}` + - `text: String` - The agent that owns this multi-agent streaming event. + 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`. - - `class BetaResponseCodeInterpreterCallCompletedEvent` + - `:output_text` - Emitted when the code interpreter call is completed. + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `item_id: String` + Citations associated with the text content. - The unique identifier of the code interpreter tool call item. + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `output_index: Integer` + - `file_id: String` - The index of the output item in the response for which the code interpreter call is completed. + The ID of the file. - - `sequence_number: Integer` + - `filename: String` - The sequence number of this event, used to order streaming events. + The filename of the file cited. - - `type: :"response.code_interpreter_call.completed"` + - `index: Integer` - The type of the event. Always `response.code_interpreter_call.completed`. + The index of the file in the list of files. - - `:"response.code_interpreter_call.completed"` + - `type: :file_citation` - - `agent: Agent{ agent_name}` + The citation type. Always `file_citation`. - The agent that owns this multi-agent streaming event. + - `:file_citation` - - `agent_name: String` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - The canonical name of the agent that produced this item. + - `end_index: Integer` - - `class BetaResponseCodeInterpreterCallInProgressEvent` + The index of the last character of the citation in the message. - Emitted when a code interpreter call is in progress. + - `start_index: Integer` - - `item_id: String` + The index of the first character of the citation in the message. - The unique identifier of the code interpreter tool call item. + - `title: String` - - `output_index: Integer` + The title of the cited resource. - The index of the output item in the response for which the code interpreter call is in progress. + - `type: :url_citation` - - `sequence_number: Integer` + The citation type. Always `url_citation`. - The sequence number of this event, used to order streaming events. + - `:url_citation` - - `type: :"response.code_interpreter_call.in_progress"` + - `url: String` - The type of the event. Always `response.code_interpreter_call.in_progress`. + The URL of the cited resource. - - `:"response.code_interpreter_call.in_progress"` + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `agent: Agent{ agent_name}` + - `container_id: String` - The agent that owns this multi-agent streaming event. + The ID of the container. - - `agent_name: String` + - `end_index: Integer` - The canonical name of the agent that produced this item. + The index of the last character of the citation in the message. - - `class BetaResponseCodeInterpreterCallInterpretingEvent` + - `file_id: String` - Emitted when the code interpreter is actively interpreting the code snippet. + The ID of the container file. - - `item_id: String` + - `filename: String` - The unique identifier of the code interpreter tool call item. + The filename of the container file cited. - - `output_index: Integer` + - `start_index: Integer` - The index of the output item in the response for which the code interpreter is interpreting code. + The index of the first character of the citation in the message. - - `sequence_number: Integer` + - `type: :container_file_citation` - The sequence number of this event, used to order streaming events. + The citation type. Always `container_file_citation`. - - `type: :"response.code_interpreter_call.interpreting"` + - `:container_file_citation` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `type: :multi_agent_call_output` - - `:"response.code_interpreter_call.interpreting"` + The item type. Always `multi_agent_call_output`. + + - `:multi_agent_call_output` + + - `id: String` + + The unique ID of this multi-agent call output. - `agent: Agent{ 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. - - `class BetaResponseCompletedEvent` + - `class ToolSearchCall` - Emitted when the model response is complete. + - `arguments: untyped` - - `response: BetaResponse` + The arguments supplied to the tool search call. - Properties of the completed response. + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` - `id: String` - Unique identifier for this Response. + The unique ID of this tool search call. - - `created_at: Float` + - `agent: Agent{ agent_name}` - Unix timestamp (in seconds) of when this Response was created. + The agent that produced this item. - - `error: BetaResponseError` + - `agent_name: String` - An error object returned when the model fails to generate a Response. + The canonical name of the agent that produced this item. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` + - `call_id: String` - The error code for the response. + The unique ID of the tool search call generated by the model. - - `:server_error` + - `execution: :server | :client` - - `:rate_limit_exceeded` + Whether tool search was executed by the server or by the client. - - `:invalid_prompt` + - `:server` - - `:bio_policy` + - `:client` - - `:vector_store_timeout` + - `status: :in_progress | :completed | :incomplete` - - `:invalid_image` + The status of the tool search call. - - `:invalid_image_format` + - `:in_progress` - - `:invalid_base64_image` + - `:completed` - - `:invalid_image_url` + - `:incomplete` - - `:image_too_large` + - `class BetaResponseToolSearchOutputItemParam` - - `:image_too_small` + - `tools: Array[BetaTool]` - - `:image_parse_error` + The loaded tool definitions returned by the tool search output. - - `:image_content_policy_violation` + - `class BetaFunctionTool` - - `:invalid_image_mode` + 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). - - `:image_file_too_large` + - `name: String` - - `:unsupported_image_media_type` + The name of the function to call. - - `:empty_image_file` + - `parameters: Hash[Symbol, untyped]` - - `:failed_to_download_image` + A JSON schema object describing the parameters of the function. - - `:image_file_not_found` + - `strict: bool` - - `message: String` + Whether strict parameter validation is enforced for this function tool. - A human-readable description of the error. + - `type: :function` - - `incomplete_details: IncompleteDetails{ reason}` + The type of the function tool. Always `function`. - Details about why the response is incomplete. + - `:function` - - `reason: :max_output_tokens | :content_filter` + - `allowed_callers: Array[:direct | :programmatic]` - The reason why the response is incomplete. + The tool invocation context(s). - - `:max_output_tokens` + - `:direct` - - `:content_filter` + - `:programmatic` - - `instructions: String | Array[BetaResponseInputItem]` + - `defer_loading: bool` - A system (or developer) message inserted into the model's context. + Whether this function is deferred and loaded via tool search. - 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. + - `description: String` - - `String = String` + A description of the function. Used by the model to determine whether or not to call the function. - A text input to the model, equivalent to a text input with the - `developer` role. + - `output_schema: Hash[Symbol, untyped]` - - `InputItemList = Array[BetaResponseInputItem]` + A JSON schema object describing the JSON value encoded in string outputs for this function. - A list of one or many input items to the model, containing - different content types. + - `class BetaFileSearchTool` - - `class BetaEasyInputMessage` + 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 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: :file_search` - - `content: String | BetaResponseInputMessageContentList` + The type of the file search tool. Always `file_search`. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `:file_search` - - `String = String` + - `vector_store_ids: Array[String]` - A text input to the model. + The IDs of the vector stores to search. - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` - A list of one or many input items to the model, containing different content - types. + A filter to apply. - - `class BetaResponseInputText` + - `class ComparisonFilter` - A text input to the model. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `text: String` + - `key: String` - The text input to the model. + The key to compare against the value. - - `type: :input_text` + - `type: :eq | :ne | :gt | 5 more` - The type of the input item. Always `input_text`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `:input_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 - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:eq` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:ne` - - `mode: :explicit` + - `:gt` - The breakpoint mode. Always `explicit`. + - `:gte` - - `:explicit` + - `:lt` - - `class BetaResponseInputImage` + - `:lte` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:in` - - `detail: :low | :high | :auto | :original` + - `:nin` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `value: String | Float | bool | Array[String | Float]` - - `:low` + The value to compare against the attribute key; supports string, number, or boolean types. - - `:high` + - `String = String` - - `:auto` + - `Float = Float` - - `:original` + - `UnionMember2 = bool` - - `type: :input_image` + - `UnionMember3 = Array[String | Float]` - The type of the input item. Always `input_image`. + - `String = String` - - `:input_image` + - `Float = Float` - - `file_id: String` + - `class CompoundFilter` - The ID of the file to be sent to the model. + Combine multiple filters using `and` or `or`. - - `image_url: String` + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class ComparisonFilter` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `mode: :explicit` + - `key: String` - The breakpoint mode. Always `explicit`. + The key to compare against the value. - - `:explicit` + - `type: :eq | :ne | :gt | 5 more` - - `class BetaResponseInputFile` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A file input to the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: :input_file` + - `:eq` - The type of the input item. Always `input_file`. + - `:ne` - - `:input_file` + - `:gt` - - `detail: :auto | :low | :high` + - `:gte` - 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`. + - `:lt` - - `:auto` + - `:lte` - - `:low` + - `:in` - - `:high` + - `:nin` - - `file_data: String` + - `value: String | Float | bool | Array[String | Float]` - The content of the file to be sent to the model. + The value to compare against the attribute key; supports string, number, or boolean types. - - `file_id: String` + - `String = String` - The ID of the file to be sent to the model. + - `Float = Float` - - `file_url: String` + - `UnionMember2 = bool` - The URL of the file to be sent to the model. + - `UnionMember3 = Array[String | Float]` - - `filename: String` + - `String = String` + + - `Float = Float` + + - `UnionMember1 = untyped` - The name of the file to be sent to the model. + - `type: :and | :or` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Type of operation: `and` or `or`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:and` - - `mode: :explicit` + - `:or` - The breakpoint mode. Always `explicit`. + - `max_num_results: Integer` - - `:explicit` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `role: :user | :assistant | :system | :developer` + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Ranking options for search. - - `:user` + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` - - `:assistant` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `:system` + - `embedding_weight: Float` - - `:developer` + The weight of the embedding in the reciprocal ranking fusion. - - `phase: :commentary` + - `text_weight: Float` - 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 weight of the text in the reciprocal ranking fusion. - - `:commentary` + - `ranker: :auto | :"default-2024-11-15"` - - `type: :message` + The ranker to use for the file search. - The type of the message input. Always `message`. + - `:auto` - - `:message` + - `:"default-2024-11-15"` - - `class Message` + - `score_threshold: Float` - 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 score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `content: BetaResponseInputMessageContentList` + - `class BetaComputerTool` - A list of one or many input items to the model, containing different content - types. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `role: :user | :system | :developer` + - `type: :computer` - The role of the message input. One of `user`, `system`, or `developer`. + The type of the computer tool. Always `computer`. - - `:user` + - `:computer` - - `:system` + - `class BetaComputerUsePreviewTool` - - `:developer` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: Agent{ agent_name}` + - `display_height: Integer` - The agent that produced this item. + The height of the computer display. - - `agent_name: String` + - `display_width: Integer` - The canonical name of the agent that produced this item. + The width of the computer display. - - `status: :in_progress | :completed | :incomplete` + - `environment: :windows | :mac | :linux | 2 more` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of computer environment to control. - - `:in_progress` + - `:windows` - - `:completed` + - `:mac` - - `:incomplete` + - `:linux` - - `type: :message` + - `:ubuntu` - The type of the message input. Always set to `message`. + - `:browser` - - `:message` + - `type: :computer_use_preview` - - `class BetaResponseOutputMessage` + The type of the computer use tool. Always `computer_use_preview`. - An output message from the model. + - `:computer_use_preview` - - `id: String` + - `class BetaWebSearchTool` - The unique ID of the output message. + 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). - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `type: :web_search | :web_search_2025_08_26` - The content of the output message. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `class BetaResponseOutputText` + - `:web_search` - A text output from the model. + - `:web_search_2025_08_26` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `filters: Filters{ allowed_domains}` - The annotations of the text output. + Filters for the search. - - `class FileCitation` + - `allowed_domains: Array[String]` - A citation to a file. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `file_id: String` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The ID of the file. + - `search_context_size: :low | :medium | :high` - - `filename: 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 filename of the file cited. + - `:low` - - `index: Integer` + - `:medium` - The index of the file in the list of files. + - `:high` - - `type: :file_citation` + - `user_location: UserLocation{ city, country, region, 2 more}` - The type of the file citation. Always `file_citation`. + The approximate location of the user. - - `:file_citation` + - `city: String` - - `class URLCitation` + Free text input for the city of the user, e.g. `San Francisco`. - A citation for a web resource used to generate a model response. + - `country: String` - - `end_index: Integer` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The index of the last character of the URL citation in the message. + - `region: String` - - `start_index: Integer` + Free text input for the region of the user, e.g. `California`. - The index of the first character of the URL citation in the message. + - `timezone: String` - - `title: String` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The title of the web resource. + - `type: :approximate` - - `type: :url_citation` + The type of location approximation. Always `approximate`. - The type of the URL citation. Always `url_citation`. + - `:approximate` - - `:url_citation` + - `class Mcp` - - `url: 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 URL of the web resource. + - `server_label: String` - - `class ContainerFileCitation` + A label for this MCP server, used to identify it in tool calls. - A citation for a container file used to generate a model response. + - `type: :mcp` - - `container_id: String` + The type of the MCP tool. Always `mcp`. - The ID of the container file. + - `:mcp` - - `end_index: Integer` + - `allowed_callers: Array[:direct | :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` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` - The filename of the container file cited. + List of allowed tool names or a filter object. - - `start_index: Integer` + - `McpAllowedTools = Array[String]` - The index of the first character of the container file citation in the message. + A string array of allowed tool names - - `type: :container_file_citation` + - `class McpToolFilter` - The type of the container file citation. Always `container_file_citation`. + A filter object to specify which tools are allowed. - - `:container_file_citation` + - `read_only: bool` - - `class FilePath` + Indicates whether or not a tool modifies data or is read-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 path to a file. + - `tool_names: Array[String]` - - `file_id: String` + List of allowed tool names. - The ID of the file. + - `authorization: String` - - `index: Integer` + 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 file in the list of files. + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` - - `type: :file_path` + 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 file path. Always `file_path`. + Currently supported `connector_id` values are: - - `:file_path` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `text: String` + - `:connector_dropbox` - The text output from the model. + - `:connector_gmail` - - `type: :output_text` + - `:connector_googlecalendar` - The type of the output text. Always `output_text`. + - `:connector_googledrive` - - `:output_text` + - `:connector_microsoftteams` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:connector_outlookcalendar` - - `token: String` + - `:connector_outlookemail` - - `bytes: Array[Integer]` + - `:connector_sharepoint` - - `logprob: Float` + - `defer_loading: bool` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + Whether this MCP tool is deferred and discovered via tool search. - - `token: String` + - `headers: Hash[Symbol, String]` - - `bytes: Array[Integer]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `logprob: Float` + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` - - `class BetaResponseOutputRefusal` + Specify which of the MCP server's tools require approval. - A refusal from the model. + - `class McpToolApprovalFilter` - - `refusal: 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 refusal explanation from the model. + - `always: Always{ read_only, tool_names}` - - `type: :refusal` + A filter object to specify which tools are allowed. - The type of the refusal. Always `refusal`. + - `read_only: bool` - - `:refusal` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `role: :assistant` + - `tool_names: Array[String]` - The role of the output message. Always `assistant`. + List of allowed tool names. - - `:assistant` + - `never: Never{ read_only, tool_names}` - - `status: :in_progress | :completed | :incomplete` + A filter object to specify which tools are allowed. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `read_only: bool` - - `: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: Array[String]` - - `:incomplete` + List of allowed tool names. - - `type: :message` + - `McpToolApprovalSetting = :always | :never` - The type of the output message. Always `message`. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `:message` + - `:always` - - `agent: Agent{ agent_name}` + - `:never` - The agent that produced this item. + - `server_description: String` - - `agent_name: String` + Optional description of the MCP server, used to provide more context. - The canonical name of the agent that produced this item. + - `server_url: String` - - `phase: :commentary` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - 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. + - `tunnel_id: String` - - `:commentary` + 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. - - `class BetaResponseFileSearchToolCall` + - `class CodeInterpreter` - 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 tool that runs Python code to help generate a response to a prompt. - - `id: String` + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` - The unique ID of the file search 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. - - `queries: Array[String]` + - `String = String` - The queries used to search for files. + The container ID. - - `status: :in_progress | :searching | :completed | 2 more` + - `class CodeInterpreterToolAuto` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `:in_progress` + - `type: :auto` - - `:searching` + Always `auto`. - - `:completed` + - `:auto` - - `:incomplete` + - `file_ids: Array[String]` - - `:failed` + An optional list of uploaded files to make available to your code. - - `type: :file_search_call` + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - The type of the file search tool call. Always `file_search_call`. + The memory limit for the code interpreter container. - - `:file_search_call` + - `:"1g"` - - `agent: Agent{ 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: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + Network access policy for the container. - The results of the file search tool call. + - `class BetaContainerNetworkPolicyDisabled` - - `attributes: Hash[Symbol, String | Float | bool]` + - `type: :disabled` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + Disable outbound network access. Always `disabled`. - - `String = String` + - `:disabled` - - `Float = Float` + - `class BetaContainerNetworkPolicyAllowlist` - - `UnionMember2 = bool` + - `allowed_domains: Array[String]` - - `file_id: String` + A list of allowed domains when type is `allowlist`. - The unique ID of the file. + - `type: :allowlist` - - `filename: String` + Allow outbound network access only to specified domains. Always `allowlist`. - The name of the file. + - `:allowlist` - - `score: Float` + - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` - The relevance score of the file - a value between 0 and 1. + Optional domain-scoped secrets for allowlisted domains. - - `text: String` + - `domain: String` - The text that was retrieved from the file. + The domain associated with the secret. - - `class BetaResponseComputerToolCall` + - `name: 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. + The name of the secret to inject for the domain. - - `id: String` + - `value: String` - The unique ID of the computer call. + The secret value to inject for the domain. - - `call_id: String` + - `type: :code_interpreter` - An identifier used when responding to the tool call with output. + The type of the code interpreter tool. Always `code_interpreter`. - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `:code_interpreter` - The pending safety checks for the computer call. + - `allowed_callers: Array[:direct | :programmatic]` - - `id: String` + The tool invocation context(s). - The ID of the pending safety check. + - `:direct` - - `code: String` + - `:programmatic` - The type of the pending safety check. + - `class ProgrammaticToolCalling` - - `message: String` + - `type: :programmatic_tool_calling` - Details about the pending safety check. + The type of the tool. Always `programmatic_tool_calling`. - - `status: :in_progress | :completed | :incomplete` + - `:programmatic_tool_calling` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class ImageGeneration` - - `:in_progress` + A tool that generates images using the GPT image models. - - `:completed` + - `type: :image_generation` - - `:incomplete` + The type of the image generation tool. Always `image_generation`. - - `type: :computer_call` + - `:image_generation` - The type of the computer call. Always `computer_call`. + - `action: :generate | :edit | :auto` - - `:computer_call` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `action: BetaComputerAction` + - `:generate` - A click action. + - `:edit` - - `class Click` + - `:auto` - A click action. + - `background: :transparent | :opaque | :auto` - - `button: :left | :right | :wheel | 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. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + `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. - - `:left` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `:right` + - `:transparent` - - `:wheel` + - `:opaque` - - `:back` + - `:auto` - - `:forward` + - `input_fidelity: :high | :low` - - `type: :click` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - Specifies the event type. For a click action, this property is always `click`. + - `:high` - - `:click` + - `:low` - - `x: Integer` + - `input_image_mask: InputImageMask{ file_id, image_url}` - The x-coordinate where the click occurred. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `y_: Integer` + - `file_id: String` - The y-coordinate where the click occurred. + File ID for the mask image. - - `keys: Array[String]` + - `image_url: String` - The keys being held while clicking. + Base64-encoded mask image. - - `class DoubleClick` + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - A double click action. + The image generation model to use. Default: `gpt-image-1`. - - `keys: Array[String]` + - `String = String` - The keys being held while double-clicking. + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` - - `type: :double_click` + The image generation model to use. Default: `gpt-image-1`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `:"gpt-image-1"` - - `:double_click` + - `:"gpt-image-1-mini"` - - `x: Integer` + - `:"gpt-image-2"` - The x-coordinate where the double click occurred. + - `:"gpt-image-2-2026-04-21"` - - `y_: Integer` + - `:"gpt-image-1.5"` - The y-coordinate where the double click occurred. + - `:"chatgpt-image-latest"` - - `class Drag` + - `moderation: :auto | :low` - A drag action. + Moderation level for the generated image. Default: `auto`. - - `path: Array[Path{ x, y_}]` + - `:auto` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `:low` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `output_compression: Integer` - - `x: Integer` + Compression level for the output image. Default: 100. - The x-coordinate. + - `output_format: :png | :webp | :jpeg` - - `y_: Integer` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The y-coordinate. + - `:png` - - `type: :drag` + - `:webp` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `:jpeg` - - `:drag` + - `partial_images: Integer` - - `keys: Array[String]` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The keys being held while dragging the mouse. + - `quality: :low | :medium | :high | :auto` - - `class Keypress` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A collection of keypresses the model would like to perform. + - `:low` - - `keys: Array[String]` + - `:medium` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `:high` - - `type: :keypress` + - `:auto` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `: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`. - - `class Move` + - `String = String` - A mouse move action. + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` - - `type: :move` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Specifies the event type. For a move action, this property is always set to `move`. + - `:"1024x1024"` - - `:move` + - `:"1024x1536"` - - `x: Integer` + - `:"1536x1024"` - The x-coordinate to move to. + - `:auto` - - `y_: Integer` + - `class LocalShell` - The y-coordinate to move to. + A tool that allows the model to execute shell commands in a local environment. - - `keys: Array[String]` + - `type: :local_shell` - The keys being held while moving the mouse. + The type of the local shell tool. Always `local_shell`. - - `class Screenshot` + - `:local_shell` - A screenshot action. + - `class BetaFunctionShellTool` - - `type: :screenshot` + A tool that allows the model to execute shell commands. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `type: :shell` - - `:screenshot` + The type of the shell tool. Always `shell`. - - `class Scroll` + - `:shell` - A scroll action. + - `allowed_callers: Array[:direct | :programmatic]` - - `scroll_x: Integer` + The tool invocation context(s). - The horizontal scroll distance. + - `:direct` - - `scroll_y: Integer` + - `:programmatic` - The vertical scroll distance. + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - - `type: :scroll` + - `class BetaContainerAuto` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `type: :container_auto` - - `:scroll` + Automatically creates a container for this request - - `x: Integer` + - `:container_auto` - The x-coordinate where the scroll occurred. + - `file_ids: Array[String]` - - `y_: Integer` + An optional list of uploaded files to make available to your code. - The y-coordinate where the scroll occurred. + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` - - `keys: Array[String]` + The memory limit for the container. - The keys being held while scrolling. + - `:"1g"` - - `class Type` + - `:"4g"` - An action to type in text. + - `:"16g"` - - `text: String` + - `:"64g"` - The text to type. + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` - - `type: :type` + Network access policy for the container. - Specifies the event type. For a type action, this property is always set to `type`. + - `class BetaContainerNetworkPolicyDisabled` - - `:type` + - `class BetaContainerNetworkPolicyAllowlist` - - `class Wait` + - `skills: Array[BetaSkillReference | BetaInlineSkill]` - A wait action. + An optional list of skills referenced by id or inline data. - - `type: :wait` + - `class BetaSkillReference` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `skill_id: String` - - `:wait` + The ID of the referenced skill. - - `actions: BetaComputerActionList` + - `type: :skill_reference` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + References a skill created with the /v1/skills endpoint. - - `class Click` + - `:skill_reference` - A click action. + - `version: String` - - `class DoubleClick` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A double click action. + - `class BetaInlineSkill` - - `class Drag` + - `description: String` - A drag action. + The description of the skill. - - `class Keypress` + - `name: String` - A collection of keypresses the model would like to perform. + The name of the skill. - - `class Move` + - `source: BetaInlineSkillSource` - A mouse move action. + Inline skill payload - - `class Screenshot` + - `data: String` - A screenshot action. + Base64-encoded skill zip bundle. - - `class Scroll` + - `media_type: :"application/zip"` - A scroll action. + The media type of the inline skill payload. Must be `application/zip`. - - `class Type` + - `:"application/zip"` - An action to type in text. + - `type: :base64` - - `class Wait` + The type of the inline skill source. Must be `base64`. - A wait action. + - `:base64` - - `agent: Agent{ agent_name}` + - `type: :inline` - The agent that produced this item. + Defines an inline skill for this request. - - `agent_name: String` + - `:inline` - The canonical name of the agent that produced this item. + - `class BetaLocalEnvironment` - - `class ComputerCallOutput` + - `type: :local` - The output of a computer tool call. + Use a local computer environment. - - `call_id: String` + - `:local` - The ID of the computer tool call that produced the output. + - `skills: Array[BetaLocalSkill]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + An optional list of skills. - A computer screenshot image used with the computer use tool. + - `description: String` - - `type: :computer_screenshot` + The description of the skill. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `name: String` - - `:computer_screenshot` + The name of the skill. - - `file_id: String` + - `path: String` - The identifier of an uploaded file that contains the screenshot. + The path to the directory containing the skill. - - `image_url: String` + - `class BetaContainerReference` - The URL of the screenshot image. + - `container_id: String` - - `type: :computer_call_output` + The ID of the referenced container. - The type of the computer tool call output. Always `computer_call_output`. + - `type: :container_reference` - - `:computer_call_output` + References a container created with the /v1/containers endpoint - - `id: String` + - `:container_reference` - The ID of the computer tool call output. + - `class BetaCustomTool` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, 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) - The safety checks reported by the API that have been acknowledged by the developer. + - `name: String` - - `id: String` + The name of the custom tool, used to identify it in tool calls. - The ID of the pending safety check. + - `type: :custom` - - `code: String` + The type of the custom tool. Always `custom`. - The type of the pending safety check. + - `:custom` - - `message: String` + - `allowed_callers: Array[:direct | :programmatic]` - Details about the pending safety check. + The tool invocation context(s). - - `agent: Agent{ agent_name}` + - `:direct` - The agent that produced this item. + - `:programmatic` - - `agent_name: String` + - `defer_loading: bool` - The canonical name of the agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `status: :in_progress | :completed | :incomplete` + - `description: String` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + Optional description of the custom tool, used to provide more context. - - `:in_progress` + - `format_: Text{ type} | Grammar{ definition, syntax, type}` - - `:completed` + The input format for the custom tool. Default is unconstrained text. - - `:incomplete` + - `class Text` - - `class BetaResponseFunctionWebSearch` + Unconstrained free-form text. - 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: :text` - - `id: String` + Unconstrained text format. Always `text`. - The unique ID of the web search tool call. + - `:text` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `class Grammar` - 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 grammar defined by the user. - - `class Search` + - `definition: String` - Action type "search" - Performs a web search query. + The grammar definition. - - `type: :search` + - `syntax: :lark | :regex` - The action type. + The syntax of the grammar definition. One of `lark` or `regex`. - - `:search` + - `:lark` - - `queries: Array[String]` + - `:regex` - The search queries. + - `type: :grammar` - - `query: String` + Grammar format. Always `grammar`. - The search query. + - `:grammar` - - `sources: Array[Source{ type, url}]` + - `class BetaNamespaceTool` - The sources used in the search. + Groups function/custom tools under a shared namespace. - - `type: :url` + - `description: String` - The type of source. Always `url`. + A description of the namespace shown to the model. - - `:url` + - `name: String` - - `url: String` + The namespace name used in tool calls (for example, `crm`). - The URL of the source. + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` - - `class OpenPage` + The function/custom tools available inside this namespace. - Action type "open_page" - Opens a specific URL from search results. + - `class Function` - - `type: :open_page` + - `name: String` - The action type. + - `type: :function` - - `:open_page` + - `:function` - - `url: String` + - `allowed_callers: Array[:direct | :programmatic]` - The URL opened by the model. + The tool invocation context(s). - - `class FindInPage` + - `:direct` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `:programmatic` - - `pattern: String` + - `defer_loading: bool` - The pattern or text to search for within the page. + Whether this function should be deferred and discovered via tool search. - - `type: :find_in_page` + - `description: String` - The action type. + - `output_schema: Hash[Symbol, untyped]` - - `:find_in_page` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `url: String` + - `parameters: untyped` - The URL of the page searched for the pattern. + - `strict: bool` - - `status: :in_progress | :searching | :completed | :failed` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The status of the web search tool call. + - `class BetaCustomTool` - - `: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) - - `:searching` + - `type: :namespace` - - `:completed` + The type of the tool. Always `namespace`. - - `:failed` + - `:namespace` - - `type: :web_search_call` + - `class BetaToolSearchTool` - The type of the web search tool call. Always `web_search_call`. + Hosted or BYOT tool search configuration for deferred tools. - - `:web_search_call` + - `type: :tool_search` - - `agent: Agent{ agent_name}` + The type of the tool. Always `tool_search`. - The agent that produced this item. + - `:tool_search` - - `agent_name: String` + - `description: String` - The canonical name of the agent that produced this item. + Description shown to the model for a client-executed tool search tool. - - `class BetaResponseFunctionToolCall` + - `execution: :server | :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 is 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` + - `parameters: untyped` - The unique ID of the function tool call generated by the model. + Parameter schema for a client-executed tool search tool. - - `name: String` + - `class BetaWebSearchPreviewTool` - The name of the function to run. + 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: :function_call` + - `type: :web_search_preview | :web_search_preview_2025_03_11` - The type of the function tool call. Always `function_call`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `:function_call` + - `:web_search_preview` - - `id: String` + - `:web_search_preview_2025_03_11` - The unique ID of the function tool call. + - `search_content_types: Array[:text | :image]` - - `agent: Agent{ agent_name}` + - `:text` - The agent that produced this item. + - `:image` - - `agent_name: String` + - `search_context_size: :low | :medium | :high` - The canonical name of the agent that produced this item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:low` - The execution context that produced this tool call. + - `:medium` - - `class Direct` + - `:high` - - `type: :direct` + - `user_location: UserLocation{ type, city, country, 2 more}` - - `:direct` + The user's location. - - `class Program` + - `type: :approximate` - - `caller_id: String` + The type of location approximation. Always `approximate`. - The call ID of the program item that produced this tool call. + - `:approximate` - - `type: :program` + - `city: String` - - `:program` + Free text input for the city of the user, e.g. `San Francisco`. - - `namespace: String` + - `country: String` - The namespace of the function to run. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: :in_progress | :completed | :incomplete` + - `region: 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: String` - - `:completed` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `:incomplete` + - `class BetaApplyPatchTool` - - `class FunctionCallOutput` + Allows the assistant to create, delete, or update files using unified diffs. - The output of a function tool call. + - `type: :apply_patch` - - `call_id: String` + The type of the tool. Always `apply_patch`. - The unique ID of the function tool call generated by the model. + - `:apply_patch` - - `output: String | BetaResponseFunctionCallOutputItemList` + - `allowed_callers: Array[:direct | :programmatic]` - Text, image, or file output of the function tool call. + The tool invocation context(s). - - `String = String` + - `:direct` - A JSON string of the output of the function tool call. + - `:programmatic` - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `type: :tool_search_output` - An array of content outputs (text, image, file) for the function tool call. + The item type. Always `tool_search_output`. - - `class BetaResponseInputTextContent` + - `:tool_search_output` - A text input to the model. + - `id: String` - - `text: String` + The unique ID of this tool search output. - The text input to the model. + - `agent: Agent{ 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: PromptCacheBreakpoint{ mode}` + - `call_id: String` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The unique ID of the tool search call generated by the model. - - `mode: :explicit` + - `execution: :server | :client` - The breakpoint mode. Always `explicit`. + Whether tool search was executed by the server or by the client. - - `:explicit` + - `:server` - - `class BetaResponseInputImageContent` + - `:client` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `status: :in_progress | :completed | :incomplete` - - `type: :input_image` + The status of the tool search output. - The type of the input item. Always `input_image`. + - `:in_progress` - - `:input_image` + - `:completed` - - `detail: :low | :high | :auto | :original` + - `:incomplete` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class AdditionalTools` - - `:low` + - `role: :developer` - - `:high` + The role that provided the additional tools. Only `developer` is supported. - - `:auto` + - `:developer` - - `:original` + - `tools: Array[BetaTool]` - - `file_id: String` + A list of additional tools made available at this item. - The ID of the file to be sent to the model. + - `class BetaFunctionTool` - - `image_url: 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 URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class BetaFileSearchTool` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + 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). - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaComputerTool` - - `mode: :explicit` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The breakpoint mode. Always `explicit`. + - `class BetaComputerUsePreviewTool` - - `:explicit` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaResponseInputFileContent` + - `class BetaWebSearchTool` - A file input to the model. + 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: :input_file` + - `class Mcp` - The type of the input item. Always `input_file`. + 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). - - `:input_file` + - `class CodeInterpreter` - - `detail: :auto | :low | :high` + A tool that runs Python code to help generate a response to a prompt. - 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`. + - `class ProgrammaticToolCalling` - - `:auto` + - `class ImageGeneration` - - `:low` + A tool that generates images using the GPT image models. - - `:high` + - `class LocalShell` - - `file_data: String` + A tool that allows the model to execute shell commands in a local environment. - The base64-encoded data of the file to be sent to the model. + - `class BetaFunctionShellTool` - - `file_id: String` + A tool that allows the model to execute shell commands. - The ID of the file to be sent to the model. + - `class BetaCustomTool` - - `file_url: 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 URL of the file to be sent to the model. + - `class BetaNamespaceTool` - - `filename: String` + Groups function/custom tools under a shared namespace. - The name of the file to be sent to the model. + - `class BetaToolSearchTool` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Hosted or BYOT tool search configuration for deferred tools. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaWebSearchPreviewTool` - - `mode: :explicit` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The breakpoint mode. Always `explicit`. + - `class BetaApplyPatchTool` - - `:explicit` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: :function_call_output` + - `type: :additional_tools` - The type of the function tool call output. Always `function_call_output`. + The item type. Always `additional_tools`. - - `:function_call_output` + - `:additional_tools` - `id: String` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of this additional tools item. - `agent: Agent{ agent_name}` @@ -141522,87 +154033,92 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class BetaResponseReasoningItem` - The execution context that produced this 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). - - `class Direct` + - `id: String` - - `type: :direct` + The unique identifier of the reasoning content. - The caller type. Always `direct`. + - `summary: Array[Summary{ text, type}]` - - `:direct` + Reasoning summary content. - - `class Program` + - `text: String` - - `caller_id: String` + A summary of the reasoning output from the model so far. - The call ID of the program item that produced this tool call. + - `type: :summary_text` - - `type: :program` + The type of the object. Always `summary_text`. - The caller type. Always `program`. + - `:summary_text` - - `:program` + - `type: :reasoning` - - `status: :in_progress | :completed | :incomplete` + The type of the object. Always `reasoning`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `:reasoning` - - `:in_progress` + - `agent: Agent{ agent_name}` - - `:completed` + The agent that produced this item. - - `:incomplete` + - `agent_name: String` - - `class AgentMessage` + The canonical name of the agent that produced this item. - A message routed between agents. + - `content: Array[Content{ text, type}]` - - `author: String` + Reasoning text content. - The sending agent identity. + - `text: String` - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + The reasoning text from the model. - Plaintext, image, or encrypted content sent between agents. + - `type: :reasoning_text` - - `class BetaResponseInputTextContent` + The type of the reasoning text. Always `reasoning_text`. - A text input to the model. + - `:reasoning_text` - - `class BetaResponseInputImageContent` + - `encrypted_content: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `class EncryptedContent` + - `status: :in_progress | :completed | :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`. + - `class BetaResponseCompactionItemParam` - - `:encrypted_content` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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 item type. Always `agent_message`. + The type of the item. Always `compaction`. - - `:agent_message` + - `:compaction` - `id: String` - The unique ID of this agent message item. + The ID of the compaction item. - `agent: Agent{ agent_name}` @@ -141612,41 +154128,35 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCall` - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action that was executed. - - - `:spawn_agent` + - `class ImageGenerationCall` - - `:interrupt_agent` + An image generation request made by the model. - - `:list_agents` + - `id: String` - - `:send_message` + The unique ID of the image generation call. - - `:followup_task` + - `result: String` - - `:wait_agent` + The generated image encoded in base64. - - `arguments: String` + - `status: :in_progress | :completed | :generating | :failed` - The action arguments as a JSON string. + The status of the image generation call. - - `call_id: String` + - `:in_progress` - The unique ID linking this call to its output. + - `:completed` - - `type: :multi_agent_call` + - `:generating` - The item type. Always `multi_agent_call`. + - `:failed` - - `:multi_agent_call` + - `type: :image_generation_call` - - `id: String` + The type of the image generation call. Always `image_generation_call`. - The unique ID of this multi-agent call. + - `:image_generation_call` - `agent: Agent{ agent_name}` @@ -141656,127 +154166,140 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput` + - `class BetaResponseCodeInterpreterToolCall` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + A tool call to run code. - The multi-agent action that produced this result. + - `id: String` - - `:spawn_agent` + The unique ID of the code interpreter tool call. - - `:interrupt_agent` + - `code: String` - - `:list_agents` + The code to run, or null if not available. - - `:send_message` + - `container_id: String` - - `:followup_task` + The ID of the container used to run the code. - - `:wait_agent` + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` - - `call_id: String` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The unique ID of the multi-agent call. + - `class Logs` - - `output: Array[Output{ text, type, annotations}]` + The logs output from the code interpreter. - Text output returned by the multi-agent action. + - `logs: String` - - `text: String` + The logs output from the code interpreter. - The text content. + - `type: :logs` - - `type: :output_text` + The type of the output. Always `logs`. - The content type. Always `output_text`. + - `:logs` - - `:output_text` + - `class Image` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + The image output from the code interpreter. - Citations associated with the text content. + - `type: :image` - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + The type of the output. Always `image`. - - `file_id: String` + - `:image` - The ID of the file. + - `url: String` - - `filename: String` + The URL of the image output from the code interpreter. - The filename of the file cited. + - `status: :in_progress | :completed | :incomplete | 2 more` - - `index: Integer` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The index of the file in the list of files. + - `:in_progress` - - `type: :file_citation` + - `:completed` - The citation type. Always `file_citation`. + - `:incomplete` - - `:file_citation` + - `:interpreting` - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `:failed` - - `end_index: Integer` + - `type: :code_interpreter_call` - The index of the last character of the citation in the message. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `start_index: Integer` + - `:code_interpreter_call` - The index of the first character of the citation in the message. + - `agent: Agent{ agent_name}` - - `title: String` + The agent that produced this item. - The title of the cited resource. + - `agent_name: String` - - `type: :url_citation` + The canonical name of the agent that produced this item. - The citation type. Always `url_citation`. + - `class LocalShellCall` - - `:url_citation` + A tool call to run a command on the local shell. - - `url: String` + - `id: String` - The URL of the cited resource. + The unique ID of the local shell call. - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `action: Action{ command, env, type, 3 more}` - - `container_id: String` + Execute a shell command on the server. - The ID of the container. + - `command: Array[String]` - - `end_index: Integer` + The command to run. - The index of the last character of the citation in the message. + - `env: Hash[Symbol, String]` - - `file_id: String` + Environment variables to set for the command. - The ID of the container file. + - `type: :exec` - - `filename: String` + The type of the local shell action. Always `exec`. - The filename of the container file cited. + - `:exec` - - `start_index: Integer` + - `timeout_ms: Integer` - The index of the first character of the citation in the message. + Optional timeout in milliseconds for the command. - - `type: :container_file_citation` + - `user: String` - The citation type. Always `container_file_citation`. + Optional user to run the command as. - - `:container_file_citation` + - `working_directory: String` - - `type: :multi_agent_call_output` + Optional working directory to run the command in. - The item type. Always `multi_agent_call_output`. + - `call_id: String` - - `:multi_agent_call_output` + The unique ID of the local shell tool call generated by the model. - - `id: String` + - `status: :in_progress | :completed | :incomplete` - The unique ID of this multi-agent call output. + 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: Agent{ agent_name}` @@ -141786,21 +154309,23 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall` + - `class LocalShellCallOutput` - - `arguments: untyped` + The output of a local shell tool call. - The arguments supplied to the tool search call. + - `id: String` - - `type: :tool_search_call` + The unique ID of the local shell tool call generated by the model. - The item type. Always `tool_search_call`. + - `output: String` - - `:tool_search_call` + A JSON string of the output of the local shell tool call. - - `id: String` + - `type: :local_shell_call_output` - The unique ID of this tool search call. + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `:local_shell_call_output` - `agent: Agent{ agent_name}` @@ -141810,1171 +154335,1179 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `call_id: String` + - `status: :in_progress | :completed | :incomplete` - The unique ID of the tool search call generated by the model. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `execution: :server | :client` + - `:in_progress` - Whether tool search was executed by the server or by the client. + - `:completed` - - `:server` + - `:incomplete` - - `:client` + - `class ShellCall` - - `status: :in_progress | :completed | :incomplete` + A tool representing a request to execute one or more shell commands. - The status of the tool search call. + - `action: Action{ commands, max_output_length, timeout_ms}` - - `:in_progress` + The shell commands and limits that describe how to run the tool call. - - `:completed` + - `commands: Array[String]` - - `:incomplete` + Ordered shell commands for the execution environment to run. - - `class BetaResponseToolSearchOutputItemParam` + - `max_output_length: Integer` - - `tools: Array[BetaTool]` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The loaded tool definitions returned by the tool search output. + - `timeout_ms: Integer` - - `class BetaFunctionTool` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `call_id: String` - - `name: String` + The unique ID of the shell tool call generated by the model. - The name of the function to call. + - `type: :shell_call` - - `parameters: Hash[Symbol, untyped]` + The type of the item. Always `shell_call`. - A JSON schema object describing the parameters of the function. + - `:shell_call` - - `strict: bool` + - `id: String` - Whether strict parameter validation is enforced for this function tool. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: :function` + - `agent: Agent{ agent_name}` - The type of the function tool. Always `function`. + The agent that produced this item. - - `:function` + - `agent_name: String` - - `allowed_callers: Array[:direct | :programmatic]` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. - `:direct` - - `:programmatic` + - `class Program` - - `defer_loading: bool` + - `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: String` + - `type: :program` - A description of the function. Used by the model to determine whether or not to call the function. + The caller type. Always `program`. - - `output_schema: Hash[Symbol, untyped]` + - `:program` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `environment: BetaLocalEnvironment | BetaContainerReference` - - `class BetaFileSearchTool` + The environment to execute the shell commands in. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class BetaLocalEnvironment` - - `type: :file_search` + - `class BetaContainerReference` - The type of the file search tool. Always `file_search`. + - `status: :in_progress | :completed | :incomplete` - - `:file_search` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `vector_store_ids: Array[String]` + - `:in_progress` - The IDs of the vector stores to search. + - `:completed` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `:incomplete` - A filter to apply. + - `class ShellCallOutput` - - `class ComparisonFilter` + The streamed output items emitted by a shell tool call. - 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 shell tool call generated by the model. - The key to compare against the value. + - `output: Array[BetaResponseFunctionShellCallOutputContent]` - - `type: :eq | :ne | :gt | 5 more` + Captured chunks of stdout and stderr output, along with their associated outcomes. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `outcome: Timeout{ type} | Exit{ exit_code, 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 exit or timeout outcome associated with this shell call. - - `:eq` + - `class Timeout` - - `:ne` + Indicates that the shell call exceeded its configured time limit. - - `:gt` + - `type: :timeout` - - `:gte` + The outcome type. Always `timeout`. - - `:lt` + - `:timeout` - - `:lte` + - `class Exit` - - `:in` + Indicates that the shell commands finished and returned an exit code. - - `:nin` + - `exit_code: Integer` - - `value: String | Float | bool | Array[untyped]` + The exit code returned by the shell process. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: :exit` - - `String = String` + The outcome type. Always `exit`. - - `Float = Float` + - `:exit` - - `UnionMember2 = bool` + - `stderr: String` - - `UnionMember3 = Array[untyped]` + Captured stderr output for the shell call. - - `class CompoundFilter` + - `stdout: String` - Combine multiple filters using `and` or `or`. + Captured stdout output for the shell call. - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + - `type: :shell_call_output` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The type of the item. Always `shell_call_output`. - - `class ComparisonFilter` + - `:shell_call_output` - 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 shell tool call output. Populated when this item is returned via API. - The key to compare against the value. + - `agent: Agent{ agent_name}` - - `type: :eq | :ne | :gt | 5 more` + The agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent_name: String` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The canonical name of the agent that produced this item. - - `:eq` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:ne` + The execution context that produced this tool call. - - `:gt` + - `class Direct` - - `:gte` + - `type: :direct` - - `:lt` + The caller type. Always `direct`. - - `:lte` + - `:direct` - - `:in` + - `class Program` - - `:nin` + - `caller_id: String` - - `value: String | Float | bool | Array[untyped]` + 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 = String` + The caller type. Always `program`. - - `Float = Float` + - `:program` - - `UnionMember2 = bool` + - `max_output_length: Integer` - - `UnionMember3 = Array[untyped]` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `UnionMember1 = untyped` + - `status: :in_progress | :completed | :incomplete` - - `type: :and | :or` + The status of the shell call output. - Type of operation: `and` or `or`. + - `:in_progress` - - `:and` + - `:completed` - - `:or` + - `:incomplete` - - `max_num_results: Integer` + - `class ApplyPatchCall` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A tool call representing a request to create, delete, or update files using diff patches. - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `call_id: String` - Ranking options for search. + The unique ID of the apply patch tool call generated by the model. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The specific create, delete, or update instruction for the apply_patch tool call. - - `embedding_weight: Float` + - `class CreateFile` - The weight of the embedding in the reciprocal ranking fusion. + Instruction for creating a new file via the apply_patch tool. - - `text_weight: Float` + - `diff: String` - The weight of the text in the reciprocal ranking fusion. + Unified diff content to apply when creating the file. - - `ranker: :auto | :"default-2024-11-15"` + - `path: String` - The ranker to use for the file search. + Path of the file to create relative to the workspace root. - - `:auto` + - `type: :create_file` - - `:"default-2024-11-15"` + The operation type. Always `create_file`. - - `score_threshold: Float` + - `:create_file` - 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. + - `class DeleteFile` - - `class BetaComputerTool` + Instruction for deleting an existing file via the apply_patch tool. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `path: String` - - `type: :computer` + Path of the file to delete relative to the workspace root. - The type of the computer tool. Always `computer`. + - `type: :delete_file` - - `:computer` + The operation type. Always `delete_file`. - - `class BetaComputerUsePreviewTool` + - `:delete_file` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class UpdateFile` - - `display_height: Integer` + Instruction for updating an existing file via the apply_patch tool. - The height of the computer display. + - `diff: String` - - `display_width: Integer` + Unified diff content to apply to the existing file. - The width of the computer display. + - `path: String` - - `environment: :windows | :mac | :linux | 2 more` + Path of the file to update relative to the workspace root. - The type of computer environment to control. + - `type: :update_file` - - `:windows` + The operation type. Always `update_file`. - - `:mac` + - `:update_file` - - `:linux` + - `status: :in_progress | :completed` - - `:ubuntu` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `:browser` + - `:in_progress` - - `type: :computer_use_preview` + - `:completed` - The type of the computer use tool. Always `computer_use_preview`. + - `type: :apply_patch_call` - - `:computer_use_preview` + The type of the item. Always `apply_patch_call`. - - `class BetaWebSearchTool` + - `:apply_patch_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 | :web_search_2025_08_26` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `agent: Agent{ agent_name}` - - `:web_search` + The agent that produced this item. - - `:web_search_2025_08_26` + - `agent_name: String` - - `filters: Filters{ allowed_domains}` + The canonical name of the agent that produced this item. - Filters for the search. + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `allowed_domains: Array[String]` + The execution context 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. + - `class Direct` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `type: :direct` - - `search_context_size: :low | :medium | :high` + The caller type. Always `direct`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `:direct` - - `:low` + - `class Program` - - `:medium` + - `caller_id: String` - - `:high` + The call ID of the program item that produced this tool call. - - `user_location: UserLocation{ city, country, region, 2 more}` + - `type: :program` - The approximate location of the user. + The caller type. Always `program`. - - `city: String` + - `:program` - Free text input for the city of the user, e.g. `San Francisco`. + - `class ApplyPatchCallOutput` - - `country: String` + The streamed output emitted by an apply patch tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `call_id: String` - - `region: String` + The unique ID of the apply patch tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `status: :completed | :failed` - - `timezone: String` + The status of the apply patch tool call output. One of `completed` or `failed`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:completed` - - `type: :approximate` + - `:failed` - The type of location approximation. Always `approximate`. + - `type: :apply_patch_call_output` - - `:approximate` + The type of the item. Always `apply_patch_call_output`. - - `class Mcp` + - `:apply_patch_call_output` - 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 apply patch tool call output. Populated when this item is returned via API. - A label for this MCP server, used to identify it in tool calls. + - `agent: Agent{ 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: Array[:direct | :programmatic]` + - `caller_: Direct{ type} | Program{ caller_id, type}` - The tool invocation context(s). + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. - `:direct` - - `:programmatic` + - `class Program` - - `allowed_tools: Array[String] | McpToolFilter{ 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[String]` + - `type: :program` - A string array of allowed tool names + The caller type. Always `program`. - - `class McpToolFilter` + - `:program` - A filter object to specify which tools are allowed. + - `output: String` - - `read_only: bool` + Optional human-readable log text from the apply patch tool (e.g., patch results or 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. + - `class McpListTools` - - `tool_names: Array[String]` + A list of tools available on an MCP server. - List of allowed tool names. + - `id: String` - - `authorization: String` + The unique ID of the list. - 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. + - `server_label: String` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + The label of the MCP server. - 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). + - `tools: Array[Tool{ input_schema, name, annotations, description}]` - Currently supported `connector_id` values are: + The tools available on the server. - - 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_schema: untyped` - - `:connector_dropbox` + The JSON schema describing the tool's input. - - `:connector_gmail` + - `name: String` - - `:connector_googlecalendar` + The name of the tool. - - `:connector_googledrive` + - `annotations: untyped` - - `:connector_microsoftteams` + Additional annotations about the tool. - - `:connector_outlookcalendar` + - `description: String` - - `:connector_outlookemail` + The description of the tool. - - `:connector_sharepoint` + - `type: :mcp_list_tools` - - `defer_loading: bool` + The type of the item. Always `mcp_list_tools`. - Whether this MCP tool is deferred and discovered via tool search. + - `:mcp_list_tools` - - `headers: Hash[Symbol, String]` + - `agent: Agent{ agent_name}` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The agent that produced this item. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `agent_name: String` - Specify which of the MCP server's tools require approval. + The canonical name of the agent that produced this item. - - `class McpToolApprovalFilter` + - `error: 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. + Error message if the server could not list tools. - - `always: Always{ read_only, tool_names}` + - `class McpApprovalRequest` - A filter object to specify which tools are allowed. + A request for human approval of a tool invocation. - - `read_only: bool` + - `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 approval request. - - `tool_names: Array[String]` + - `arguments: String` - List of allowed tool names. + A JSON string of arguments for the tool. - - `never: Never{ read_only, tool_names}` + - `name: String` - A filter object to specify which tools are allowed. + The name of the tool to run. - - `read_only: bool` + - `server_label: 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 label of the MCP server making the request. - - `tool_names: Array[String]` + - `type: :mcp_approval_request` - List of allowed tool names. + The type of the item. Always `mcp_approval_request`. - - `McpToolApprovalSetting = :always | :never` + - `:mcp_approval_request` - 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: Agent{ agent_name}` - - `:always` + The agent that produced this item. - - `:never` + - `agent_name: String` - - `server_description: String` + The canonical name of the agent that produced this item. - Optional description of the MCP server, used to provide more context. + - `class McpApprovalResponse` - - `server_url: String` + A response to an MCP approval request. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `approval_request_id: String` - - `tunnel_id: String` + The ID of the approval request being answered. - 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. + - `approve: bool` - - `class CodeInterpreter` + Whether the request was approved. - A tool that runs Python code to help generate a response to a prompt. + - `type: :mcp_approval_response` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + The type of the item. Always `mcp_approval_response`. - 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. + - `:mcp_approval_response` - - `String = String` + - `id: String` - The container ID. + The unique ID of the approval response - - `class CodeInterpreterToolAuto` + - `agent: Agent{ 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` + - `reason: String` - - `file_ids: Array[String]` + Optional reason for the decision. - An optional list of uploaded files to make available to your code. + - `class McpCall` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + An invocation of a tool on an MCP server. - The memory limit for the code interpreter container. + - `id: String` - - `:"1g"` + The unique ID of the tool call. - - `:"4g"` + - `arguments: String` - - `:"16g"` + A JSON string of the arguments passed to the tool. - - `:"64g"` + - `name: String` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + The name of the tool that was run. - Network access policy for the container. + - `server_label: String` - - `class BetaContainerNetworkPolicyDisabled` + The label of the MCP server running the tool. - - `type: :disabled` + - `type: :mcp_call` - Disable outbound network access. Always `disabled`. + The type of the item. Always `mcp_call`. - - `:disabled` + - `:mcp_call` - - `class BetaContainerNetworkPolicyAllowlist` + - `agent: Agent{ agent_name}` - - `allowed_domains: Array[String]` + The agent that produced this item. - A list of allowed domains when type is `allowlist`. + - `agent_name: String` - - `type: :allowlist` + The canonical name of the agent that produced this item. - Allow outbound network access only to specified domains. Always `allowlist`. + - `approval_request_id: String` - - `:allowlist` + 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. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `error: String` - Optional domain-scoped secrets for allowlisted domains. + The error from the tool call, if any. - - `domain: String` + - `output: String` - The domain associated with the secret. + The output from the tool call. - - `name: String` + - `status: :in_progress | :completed | :incomplete | 2 more` - The name of the secret to inject for the domain. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `value: String` + - `:in_progress` - The secret value to inject for the domain. + - `:completed` - - `type: :code_interpreter` + - `:incomplete` - The type of the code interpreter tool. Always `code_interpreter`. + - `:calling` - - `:code_interpreter` + - `:failed` - - `allowed_callers: Array[:direct | :programmatic]` + - `class BetaResponseCustomToolCallOutput` - The tool invocation context(s). + The output of a custom tool call from your code, being sent back to the model. - - `:direct` + - `call_id: String` - - `:programmatic` + The call ID, used to map this custom tool call output to a custom tool call. - - `class ProgrammaticToolCalling` + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - - `type: :programmatic_tool_calling` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The type of the tool. Always `programmatic_tool_calling`. + - `String = String` - - `:programmatic_tool_calling` + A string of the output of the custom tool call. - - `class ImageGeneration` + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` - A tool that generates images using the GPT image models. + Text, image, or file output of the custom tool call. - - `type: :image_generation` + - `class BetaResponseInputText` - The type of the image generation tool. Always `image_generation`. + A text input to the model. - - `:image_generation` + - `class BetaResponseInputImage` - - `action: :generate | :edit | :auto` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class BetaResponseInputFile` - - `:generate` + A file input to the model. - - `:edit` + - `type: :custom_tool_call_output` - - `:auto` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `background: :transparent | :opaque | :auto` + - `:custom_tool_call_output` - 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 unique ID of the custom tool call output in the OpenAI platform. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `agent: Agent{ 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: :high | :low` + - `caller_: Direct{ type} | Program{ 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` + - `class Direct` - - `:low` + - `type: :direct` - - `input_image_mask: InputImageMask{ file_id, image_url}` + The caller type. Always `direct`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `:direct` - - `file_id: String` + - `class Program` - File ID for the mask image. + - `caller_id: String` - - `image_url: String` + The call ID of the program item that produced this tool call. - Base64-encoded mask image. + - `type: :program` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The caller type. Always `program`. - The image generation model to use. Default: `gpt-image-1`. + - `:program` - - `String = String` + - `class BetaResponseCustomToolCall` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + A call to a custom tool created by the model. - The image generation model to use. Default: `gpt-image-1`. + - `call_id: String` - - `:"gpt-image-1"` + An identifier used to map this custom tool call to a tool call output. - - `:"gpt-image-1-mini"` + - `input: String` - - `:"gpt-image-2"` + The input for the custom tool call generated by the model. - - `:"gpt-image-2-2026-04-21"` + - `name: String` - - `:"gpt-image-1.5"` + The name of the custom tool being called. - - `:"chatgpt-image-latest"` + - `type: :custom_tool_call` - - `moderation: :auto | :low` + The type of the custom tool call. Always `custom_tool_call`. - Moderation level for the generated image. Default: `auto`. + - `:custom_tool_call` - - `:auto` + - `id: String` - - `:low` + The unique ID of the custom tool call in the OpenAI platform. - - `output_compression: Integer` + - `agent: Agent{ agent_name}` - Compression level for the output image. Default: 100. + The agent that produced this item. - - `output_format: :png | :webp | :jpeg` + - `agent_name: String` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The canonical name of the agent that produced this item. - - `:png` + - `caller_: Direct{ type} | Program{ caller_id, type}` - - `:webp` + The execution context that produced this tool call. - - `:jpeg` + - `class Direct` - - `partial_images: Integer` + - `type: :direct` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `:direct` - - `quality: :low | :medium | :high | :auto` + - `class Program` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `caller_id: String` - - `:low` + The call ID of the program item that produced this tool call. - - `:medium` + - `type: :program` - - `:high` + - `:program` - - `:auto` + - `namespace: String` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + The namespace of the custom tool being called. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class CompactionTrigger` - - `String = String` + Compacts the current context. Must be the final input item. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `type: :compaction_trigger` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The type of the item. Always `compaction_trigger`. - - `:"1024x1024"` + - `:compaction_trigger` - - `:"1024x1536"` + - `agent: Agent{ agent_name}` - - `:"1536x1024"` + The agent that produced this item. - - `:auto` + - `agent_name: String` - - `class LocalShell` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `class ItemReference` - - `type: :local_shell` + An internal identifier for an item to reference. - The type of the local shell tool. Always `local_shell`. + - `id: String` - - `:local_shell` + The ID of the item to reference. - - `class BetaFunctionShellTool` + - `agent: Agent{ 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` + - `type: :item_reference` - - `allowed_callers: Array[:direct | :programmatic]` + The type of item to reference. Always `item_reference`. - The tool invocation context(s). + - `:item_reference` - - `:direct` + - `class Program` - - `:programmatic` + - `id: String` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + The unique ID of this program item. - - `class BetaContainerAuto` + - `call_id: String` - - `type: :container_auto` + The stable call ID of the program item. - Automatically creates a container for this request + - `code: String` - - `:container_auto` + The JavaScript source executed by programmatic tool calling. - - `file_ids: Array[String]` + - `fingerprint: String` - An optional list of uploaded files to make available to your code. + Opaque program replay fingerprint that must be round-tripped. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `type: :program` - The memory limit for the container. + The item type. Always `program`. - - `:"1g"` + - `:program` - - `:"4g"` + - `agent: Agent{ agent_name}` - - `:"16g"` + The agent that produced this item. - - `:"64g"` + - `agent_name: String` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + The canonical name of the agent that produced this item. - Network access policy for the container. + - `class ProgramOutput` - - `class BetaContainerNetworkPolicyDisabled` + - `id: String` - - `class BetaContainerNetworkPolicyAllowlist` + The unique ID of this program output item. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `call_id: String` - An optional list of skills referenced by id or inline data. + The call ID of the program item. - - `class BetaSkillReference` + - `result: String` - - `skill_id: String` + The result produced by the program item. - The ID of the referenced skill. + - `status: :completed | :incomplete` - - `type: :skill_reference` + The terminal status of the program output. - References a skill created with the /v1/skills endpoint. + - `:completed` - - `:skill_reference` + - `:incomplete` - - `version: String` + - `type: :program_output` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The item type. Always `program_output`. - - `class BetaInlineSkill` + - `:program_output` - - `description: String` + - `agent: Agent{ 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. - - `source: BetaInlineSkillSource` +- `instructions: String` - Inline skill payload + 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. - - `data: String` +- `model: String` - Base64-encoded skill zip bundle. + 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. - - `media_type: :"application/zip"` +- `parallel_tool_calls: bool` - The media type of the inline skill payload. Must be `application/zip`. + Whether to allow the model to run tool calls in parallel. - - `:"application/zip"` +- `personality: String | :friendly | :pragmatic` - - `type: :base64` + 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 type of the inline skill source. Must be `base64`. + - `String = String` - - `:base64` + - `Personality = :friendly | :pragmatic` - - `type: :inline` + 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. - Defines an inline skill for this request. + - `:friendly` - - `:inline` + - `:pragmatic` - - `class BetaLocalEnvironment` +- `previous_response_id: String` - - `type: :local` + 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`. - Use a local computer environment. +- `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` - - `:local` + **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `skills: Array[BetaLocalSkill]` + - `context: :auto | :current_turn | :all_turns` - An optional list of skills. + 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. - - `description: String` + - `:auto` - The description of the skill. + - `:current_turn` - - `name: String` + - `:all_turns` - The name of the skill. + - `effort: :none | :minimal | :low | 4 more` - - `path: 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 path to the directory containing the skill. + - `:none` - - `class BetaContainerReference` + - `:minimal` - - `container_id: String` + - `:low` - The ID of the referenced container. + - `:medium` - - `type: :container_reference` + - `:high` - References a container created with the /v1/containers endpoint + - `:xhigh` - - `:container_reference` + - `:max` - - `class BetaCustomTool` + - `generate_summary: :auto | :concise | :detailed` - 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) + **Deprecated:** use `summary` instead. - - `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 name of the custom tool, used to identify it in tool calls. + - `:auto` - - `type: :custom` + - `:concise` - The type of the custom tool. Always `custom`. + - `:detailed` - - `:custom` + - `mode: String | :standard | :pro` - - `allowed_callers: Array[:direct | :programmatic]` + Controls the reasoning execution mode for the request. - The tool invocation context(s). + When returned on a response, this is the effective execution mode. - - `:direct` + - `String = String` - - `:programmatic` + - `Mode = :standard | :pro` - - `defer_loading: bool` + Controls the reasoning execution mode for the request. - Whether this tool should be deferred and discovered via tool search. + When returned on a response, this is the effective execution mode. - - `description: String` + - `:standard` - Optional description of the custom tool, used to provide more context. + - `:pro` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `summary: :auto | :concise | :detailed` - The input format for the custom tool. Default is unconstrained 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`. - - `class Text` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Unconstrained free-form text. + - `:auto` - - `type: :text` + - `:concise` - Unconstrained text format. Always `text`. + - `:detailed` - - `:text` +- `text: Text{ format_, verbosity}` - - `class Grammar` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A grammar defined by the user. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `definition: String` + - `format_: BetaResponseFormatTextConfig` - The grammar definition. + An object specifying the format that the model must output. - - `syntax: :lark | :regex` + 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 syntax of the grammar definition. One of `lark` or `regex`. + The default format is `{ "type": "text" }` with no additional options. - - `:lark` + **Not recommended for gpt-4o and newer models:** - - `:regex` + 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: :grammar` + - `class Text` - Grammar format. Always `grammar`. + Default response format. Used to generate text responses. - - `:grammar` + - `type: :text` - - `class BetaNamespaceTool` + The type of response format being defined. Always `text`. - Groups function/custom tools under a shared namespace. + - `:text` - - `description: String` + - `class BetaResponseFormatTextJSONSchemaConfig` - A description of the namespace shown to the model. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: String` - The namespace name used in tool calls (for example, `crm`). - - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + 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 function/custom tools available inside this namespace. + - `schema: Hash[Symbol, untyped]` - - `class Function` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `name: String` + - `type: :json_schema` - - `type: :function` + The type of response format being defined. Always `json_schema`. - - `:function` + - `:json_schema` - - `allowed_callers: Array[:direct | :programmatic]` + - `description: String` - The tool invocation context(s). + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `:direct` + - `strict: bool` - - `: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](https://platform.openai.com/docs/guides/structured-outputs). - - `defer_loading: bool` + - `class JSONObject` - Whether this function should be deferred and discovered via tool search. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `description: String` + - `type: :json_object` - - `output_schema: Hash[Symbol, untyped]` + The type of response format being defined. Always `json_object`. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `:json_object` - - `parameters: untyped` + - `verbosity: :low | :medium | :high` - - `strict: bool` + 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`. - 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. + - `:low` - - `class BetaCustomTool` + - `:medium` - 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) + - `:high` - - `type: :namespace` +- `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` - The type of the tool. Always `namespace`. + Controls which tool the model should use, if any. - - `:namespace` + - `BetaToolChoiceOptions = :none | :auto | :required` - - `class BetaToolSearchTool` + Controls which (if any) tool is called by the model. - Hosted or BYOT tool search configuration for deferred tools. + `none` means the model will not call any tool and instead generates a message. - - `type: :tool_search` + `auto` means the model can pick between generating a message or calling one or + more tools. - The type of the tool. Always `tool_search`. + `required` means the model must call one or more tools. - - `:tool_search` + - `:none` - - `description: String` + - `:auto` - Description shown to the model for a client-executed tool search tool. + - `:required` - - `execution: :server | :client` + - `class BetaToolChoiceAllowed` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `:server` + - `mode: :auto | :required` - - `:client` + Constrains the tools available to the model to a pre-defined set. - - `parameters: untyped` + `auto` allows the model to pick from among the allowed tools and generate a + message. - Parameter schema for a client-executed tool search tool. + `required` requires the model to call one or more of the allowed tools. - - `class BetaWebSearchPreviewTool` + - `:auto` - 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` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `tools: Array[Hash[Symbol, untyped]]` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + A list of tool definitions that the model should be allowed to call. - - `:web_search_preview` + For the Responses API, the list of tool definitions might look like: - - `:web_search_preview_2025_03_11` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `search_content_types: Array[:text | :image]` + - `type: :allowed_tools` - - `:text` + Allowed tool configuration type. Always `allowed_tools`. - - `:image` + - `:allowed_tools` - - `search_context_size: :low | :medium | :high` + - `class BetaToolChoiceTypes` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + 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). - - `:low` + - `type: :file_search | :web_search_preview | :computer | 5 more` - - `:medium` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `:high` + Allowed values are: - - `user_location: UserLocation{ 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: String` + - `:computer_use` - Free text input for the city of the user, e.g. `San Francisco`. + - `:web_search_preview_2025_03_11` - - `country: 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: String` + - `class BetaToolChoiceFunction` - 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: 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. - - `class BetaApplyPatchTool` + - `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`. + - `class BetaToolChoiceMcp` - - `:apply_patch` + Use this option to force the model to call a specific tool on a remote MCP server. - - `allowed_callers: Array[:direct | :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: String` - - `:tool_search_output` + The name of the tool to call on the server. - - `id: String` + - `class BetaToolChoiceCustom` - The unique ID of this tool search output. + Use this option to force the model to call a specific custom tool. - - `agent: Agent{ 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: String` + - `:custom` - The unique ID of the tool search call generated by the model. + - `class BetaSpecificProgrammaticToolCallingParam` - - `execution: :server | :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` + - `class BetaToolChoiceApplyPatch` - - `status: :in_progress | :completed | :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` + - `class BetaToolChoiceShell` - - `class AdditionalTools` + 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[BetaTool]` +- `tools: Array[BetaTool]` - 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. - `class BetaFunctionTool` @@ -143040,18531 +155573,19755 @@ puts(beta_compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: :additional_tools` +- `truncation: :auto | :disabled` - The item type. Always `additional_tools`. + 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. - - `:additional_tools` + - `:auto` + + - `:disabled` + +- `betas: Array[:"responses_multi_agent=v1"]` + + - `:"responses_multi_agent=v1"` + +### Returns + +- `class InputTokenCountResponse` + + - `input_tokens: Integer` + + - `object: :"response.input_tokens"` + + - `:"response.input_tokens"` + +### Example + +```ruby +require "openai" + +openai = OpenAI::Client.new(api_key: "My API Key") + +response = openai.beta.responses.input_tokens.count + +puts(response) +``` + +#### Response + +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` + +### Example + +```ruby +require "openai" + +openai = OpenAI::Client.new + +response = openai.responses.input_tokens.count(model: "gpt-5", input: "Tell me a joke.") + +puts(response) +``` + +#### Response + +```json +{ + "object": "response.input_tokens", + "input_tokens": 11 +} +``` + +## Domain Types + +### Input Token Count Response + +- `class InputTokenCountResponse` + + - `input_tokens: Integer` + + - `object: :"response.input_tokens"` + + - `:"response.input_tokens"` + +# ChatKit + +## Domain Types + +### ChatKit Workflow + +- `class ChatKitWorkflow` + + Workflow metadata and state returned for the session. - `id: String` - The unique ID of this additional tools item. + Identifier of the workflow backing the session. - - `agent: Agent{ agent_name}` + - `state_variables: Hash[Symbol, String | bool | Float]` - 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 = String` - The canonical name of the agent that produced this item. + - `UnionMember1 = bool` - - `class BetaResponseReasoningItem` + - `Float = Float` - 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). + - `tracing: Tracing{ enabled}` + + Tracing settings applied to the workflow. + + - `enabled: bool` + + Indicates whether tracing is enabled. + + - `version: String` + + Specific workflow version used for the session. Defaults to null when using the latest deployment. + +# Sessions + +## Cancel chat session + +`beta.chatkit.sessions.cancel(session_id) -> ChatSession` + +**post** `/chatkit/sessions/{session_id}/cancel` + +Cancel an active ChatKit session and return its most recent metadata. + +Cancelling prevents new requests from using the issued client secret. + +### Parameters + +- `session_id: String` + +### Returns + +- `class ChatSession` + + Represents a ChatKit session and its resolved configuration. - `id: String` - The unique identifier of the reasoning content. + Identifier for the ChatKit session. - - `summary: Array[Summary{ text, type}]` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - Reasoning summary content. + Resolved ChatKit feature configuration for the session. - - `text: String` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - A summary of the reasoning output from the model so far. + Automatic thread titling preferences. - - `type: :summary_text` + - `enabled: bool` - The type of the object. Always `summary_text`. + Whether automatic thread titling is enabled. - - `:summary_text` + - `file_upload: ChatSessionFileUpload` - - `type: :reasoning` + Upload settings for the session. - The type of the object. Always `reasoning`. + - `enabled: bool` - - `:reasoning` + Indicates if uploads are enabled for the session. - - `agent: Agent{ agent_name}` + - `max_file_size: Integer` - The agent that produced this item. + Maximum upload size in megabytes. - - `agent_name: String` + - `max_files: Integer` - The canonical name of the agent that produced this item. + Maximum number of uploads allowed during the session. - - `content: Array[Content{ text, type}]` + - `history: ChatSessionHistory` - Reasoning text content. + History retention configuration. - - `text: String` + - `enabled: bool` - The reasoning text from the model. + Indicates if chat history is persisted for the session. - - `type: :reasoning_text` + - `recent_threads: Integer` - The type of the reasoning text. Always `reasoning_text`. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `:reasoning_text` + - `client_secret: String` - - `encrypted_content: String` + Ephemeral client secret that authenticates session requests. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `expires_at: Integer` - - `status: :in_progress | :completed | :incomplete` + Unix timestamp (in seconds) for when the session expires. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `max_requests_per_1_minute: Integer` - - `:in_progress` + Convenience copy of the per-minute request limit. - - `:completed` + - `object: :"chatkit.session"` - - `:incomplete` + Type discriminator that is always `chatkit.session`. - - `class BetaResponseCompactionItemParam` + - `:"chatkit.session"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `rate_limits: ChatSessionRateLimits` - - `encrypted_content: String` + Resolved rate limit values. - The encrypted content of the compaction summary. + - `max_requests_per_1_minute: Integer` - - `type: :compaction` + Maximum allowed requests per one-minute window. - The type of the item. Always `compaction`. + - `status: ChatSessionStatus` - - `:compaction` + Current lifecycle state of the session. + + - `:active` + + - `:expired` + + - `:cancelled` + + - `user: String` + + User identifier associated with the session. + + - `workflow: ChatKitWorkflow` + + Workflow metadata for the session. - `id: String` - The ID of the compaction item. + Identifier of the workflow backing the session. - - `agent: Agent{ agent_name}` + - `state_variables: Hash[Symbol, String | bool | Float]` - 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 = String` - The canonical name of the agent that produced this item. + - `UnionMember1 = bool` - - `class ImageGenerationCall` + - `Float = Float` - An image generation request made by the model. + - `tracing: Tracing{ enabled}` - - `id: String` + Tracing settings applied to the workflow. - The unique ID of the image generation call. + - `enabled: bool` - - `result: String` + Indicates whether tracing is enabled. - The generated image encoded in base64. + - `version: String` - - `status: :in_progress | :completed | :generating | :failed` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - The status of the image generation call. +### Example - - `:in_progress` +```ruby +require "openai" - - `:completed` +openai = OpenAI::Client.new(api_key: "My API Key") - - `:generating` +chat_session = openai.beta.chatkit.sessions.cancel("cksess_123") - - `:failed` +puts(chat_session) +``` - - `type: :image_generation_call` +#### Response - The type of the image generation call. Always `image_generation_call`. +```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" + } +} +``` - - `:image_generation_call` +### Example - - `agent: Agent{ agent_name}` +```ruby +require "openai" - The agent that produced this item. +openai = OpenAI::Client.new - - `agent_name: String` +chat_session = openai.beta.chatkit.sessions.cancel("cksess_123") - The canonical name of the agent that produced this item. +puts(chat_session) +``` - - `class BetaResponseCodeInterpreterToolCall` +#### Response - A tool call to run code. +```json +{ + "id": "cksess_123", + "object": "chatkit.session", + "workflow": { + "id": "workflow_alpha", + "version": "1" + }, + "scope": { + "customer_id": "cust_456" + }, + "max_requests_per_1_minute": 30, + "ttl_seconds": 900, + "status": "cancelled", + "cancelled_at": 1712345678 +} +``` + +## Create ChatKit session + +`beta.chatkit.sessions.create(**kwargs) -> ChatSession` + +**post** `/chatkit/sessions` + +Create a ChatKit session. + +### Parameters + +- `user: String` + + A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + +- `workflow: ChatSessionWorkflowParam` + + Workflow that powers the session. - `id: String` - The unique ID of the code interpreter tool call. + Identifier for the workflow invoked by the session. - - `code: String` + - `state_variables: Hash[Symbol, String | bool | Float]` - The code to run, or null if not available. + 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. - - `container_id: String` + - `String = String` - The ID of the container used to run the code. + - `UnionMember1 = bool` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + - `Float = Float` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `tracing: Tracing{ enabled}` - - `class Logs` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - The logs output from the code interpreter. + - `enabled: bool` - - `logs: String` + Whether tracing is enabled during the session. Defaults to true. - The logs output from the code interpreter. + - `version: String` - - `type: :logs` + Specific workflow version to run. Defaults to the latest deployed version. - The type of the output. Always `logs`. +- `chatkit_configuration: ChatSessionChatKitConfigurationParam` - - `:logs` + Optional overrides for ChatKit runtime configuration features - - `class Image` + - `automatic_thread_titling: AutomaticThreadTitling{ enabled}` - The image output from the code interpreter. + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `type: :image` + - `enabled: bool` - The type of the output. Always `image`. + Enable automatic thread title generation. Defaults to true. - - `:image` + - `file_upload: FileUpload{ enabled, max_file_size, max_files}` - - `url: String` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - The URL of the image output from the code interpreter. + - `enabled: bool` - - `status: :in_progress | :completed | :incomplete | 2 more` + Enable uploads for this session. Defaults to false. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `max_file_size: Integer` - - `:in_progress` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `:completed` + - `max_files: Integer` - - `:incomplete` + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `:interpreting` + - `history: History{ enabled, recent_threads}` - - `:failed` + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - - `type: :code_interpreter_call` + - `enabled: bool` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Enables chat users to access previous ChatKit threads. Defaults to true. - - `:code_interpreter_call` + - `recent_threads: Integer` - - `agent: Agent{ agent_name}` + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - The agent that produced this item. +- `expires_after: ChatSessionExpiresAfterParam` - - `agent_name: String` + Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - The canonical name of the agent that produced this item. + - `anchor: :created_at` - - `class LocalShellCall` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - A tool call to run a command on the local shell. + - `:created_at` - - `id: String` + - `seconds: Integer` - The unique ID of the local shell call. + Number of seconds after the anchor when the session expires. - - `action: Action{ command, env, type, 3 more}` +- `rate_limits: ChatSessionRateLimitsParam` - Execute a shell command on the server. + Optional override for per-minute request limits. When omitted, defaults to 10. - - `command: Array[String]` + - `max_requests_per_1_minute: Integer` - The command to run. + Maximum number of requests allowed per minute for the session. Defaults to 10. - - `env: Hash[Symbol, String]` +### Returns - Environment variables to set for the command. +- `class ChatSession` - - `type: :exec` + Represents a ChatKit session and its resolved configuration. - The type of the local shell action. Always `exec`. + - `id: String` - - `:exec` + Identifier for the ChatKit session. - - `timeout_ms: Integer` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - Optional timeout in milliseconds for the command. + Resolved ChatKit feature configuration for the session. - - `user: String` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - Optional user to run the command as. + Automatic thread titling preferences. - - `working_directory: String` + - `enabled: bool` - Optional working directory to run the command in. + Whether automatic thread titling is enabled. - - `call_id: String` + - `file_upload: ChatSessionFileUpload` - The unique ID of the local shell tool call generated by the model. + Upload settings for the session. - - `status: :in_progress | :completed | :incomplete` + - `enabled: bool` - The status of the local shell call. + Indicates if uploads are enabled for the session. - - `:in_progress` + - `max_file_size: Integer` - - `:completed` + Maximum upload size in megabytes. - - `:incomplete` + - `max_files: Integer` - - `type: :local_shell_call` + Maximum number of uploads allowed during the session. - The type of the local shell call. Always `local_shell_call`. + - `history: ChatSessionHistory` - - `:local_shell_call` + History retention configuration. - - `agent: Agent{ agent_name}` + - `enabled: bool` - The agent that produced this item. + Indicates if chat history is persisted for the session. - - `agent_name: String` + - `recent_threads: Integer` - The canonical name of the agent that produced this item. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `class LocalShellCallOutput` + - `client_secret: String` - The output of a local shell tool call. + Ephemeral client secret that authenticates session requests. - - `id: String` + - `expires_at: Integer` - The unique ID of the local shell tool call generated by the model. + Unix timestamp (in seconds) for when the session expires. - - `output: String` + - `max_requests_per_1_minute: Integer` - A JSON string of the output of the local shell tool call. + Convenience copy of the per-minute request limit. - - `type: :local_shell_call_output` + - `object: :"chatkit.session"` - The type of the local shell tool call output. Always `local_shell_call_output`. + Type discriminator that is always `chatkit.session`. + + - `:"chatkit.session"` + + - `rate_limits: ChatSessionRateLimits` + + Resolved rate limit values. + + - `max_requests_per_1_minute: Integer` + + Maximum allowed requests per one-minute window. - - `:local_shell_call_output` + - `status: ChatSessionStatus` - - `agent: Agent{ agent_name}` + Current lifecycle state of the session. - The agent that produced this item. + - `:active` - - `agent_name: String` + - `:expired` - The canonical name of the agent that produced this item. + - `:cancelled` - - `status: :in_progress | :completed | :incomplete` + - `user: String` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + User identifier associated with the session. - - `:in_progress` + - `workflow: ChatKitWorkflow` - - `:completed` + Workflow metadata for the session. - - `:incomplete` + - `id: String` - - `class ShellCall` + Identifier of the workflow backing the session. - A tool representing a request to execute one or more shell commands. + - `state_variables: Hash[Symbol, String | bool | Float]` - - `action: Action{ commands, max_output_length, timeout_ms}` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - The shell commands and limits that describe how to run the tool call. + - `String = String` - - `commands: Array[String]` + - `UnionMember1 = bool` - Ordered shell commands for the execution environment to run. + - `Float = Float` - - `max_output_length: Integer` + - `tracing: Tracing{ enabled}` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Tracing settings applied to the workflow. - - `timeout_ms: Integer` + - `enabled: bool` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Indicates whether tracing is enabled. - - `call_id: String` + - `version: String` - The unique ID of the shell tool call generated by the model. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `type: :shell_call` +### Example - The type of the item. Always `shell_call`. +```ruby +require "openai" - - `:shell_call` +openai = OpenAI::Client.new(api_key: "My API Key") - - `id: String` +chat_session = openai.beta.chatkit.sessions.create(user: "x", workflow: {id: "id"}) - The unique ID of the shell tool call. Populated when this item is returned via API. +puts(chat_session) +``` - - `agent: Agent{ agent_name}` +#### Response - The agent that produced this item. +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - - `agent_name: String` +### Example - The canonical name of the agent that produced this item. +```ruby +require "openai" - - `caller_: Direct{ type} | Program{ caller_id, type}` +openai = OpenAI::Client.new - The execution context that produced this tool call. +chat_session = openai.beta.chatkit.sessions.create(user: "user", workflow: {id: "id"}) - - `class Direct` +puts(chat_session) +``` - - `type: :direct` +#### Response - The caller type. Always `direct`. +```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" +} +``` - - `:direct` +# Threads - - `class Program` +## List ChatKit thread items - - `caller_id: String` +`beta.chatkit.threads.list_items(thread_id, **kwargs) -> ConversationCursorPage` - The call ID of the program item that produced this tool call. +**get** `/chatkit/threads/{thread_id}/items` - - `type: :program` +List items that belong to a ChatKit thread. - The caller type. Always `program`. +### Parameters - - `:program` +- `thread_id: String` - - `environment: BetaLocalEnvironment | BetaContainerReference` +- `after: String` - The environment to execute the shell commands in. + List items created after this thread item ID. Defaults to null for the first page. - - `class BetaLocalEnvironment` +- `before: String` - - `class BetaContainerReference` + List items created before this thread item ID. Defaults to null for the newest results. - - `status: :in_progress | :completed | :incomplete` +- `limit: Integer` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Maximum number of thread items to return. Defaults to 20. - - `:in_progress` +- `order: :asc | :desc` - - `:completed` + Sort order for results by creation time. Defaults to `desc`. - - `:incomplete` + - `:asc` - - `class ShellCallOutput` + - `:desc` - The streamed output items emitted by a shell tool call. +### Returns - - `call_id: String` +- `ChatKitThreadUserMessageItem | ChatKitThreadAssistantMessageItem | ChatKitWidgetItem | 3 more` - The unique ID of the shell tool call generated by the model. + - `class ChatKitThreadUserMessageItem` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + User-authored messages within a thread. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `id: String` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + Identifier of the thread item. - The exit or timeout outcome associated with this shell call. + - `attachments: Array[ChatKitAttachment]` - - `class Timeout` + Attachments associated with the user message. Defaults to an empty list. - Indicates that the shell call exceeded its configured time limit. + - `id: String` - - `type: :timeout` + Identifier for the attachment. - The outcome type. Always `timeout`. + - `mime_type: String` - - `:timeout` + MIME type of the attachment. - - `class Exit` + - `name: String` - Indicates that the shell commands finished and returned an exit code. + Original display name for the attachment. - - `exit_code: Integer` + - `preview_url: String` - The exit code returned by the shell process. + Preview URL for rendering the attachment inline. - - `type: :exit` + - `type: :image | :file` - The outcome type. Always `exit`. + Attachment discriminator. - - `:exit` + - `:image` - - `stderr: String` + - `:file` - Captured stderr output for the shell call. + - `content: Array[InputText{ text, type} | QuotedText{ text, type}]` - - `stdout: String` + Ordered content elements supplied by the user. - Captured stdout output for the shell call. + - `class InputText` - - `type: :shell_call_output` + Text block that a user contributed to the thread. - The type of the item. Always `shell_call_output`. + - `text: String` - - `:shell_call_output` + Plain-text content supplied by the user. - - `id: String` + - `type: :input_text` - The unique ID of the shell tool call output. Populated when this item is returned via API. + Type discriminator that is always `input_text`. - - `agent: Agent{ agent_name}` + - `:input_text` - The agent that produced this item. + - `class QuotedText` - - `agent_name: String` + Quoted snippet that the user referenced in their message. - The canonical name of the agent that produced this item. + - `text: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Quoted text content. - The execution context that produced this tool call. + - `type: :quoted_text` - - `class Direct` + Type discriminator that is always `quoted_text`. - - `type: :direct` + - `:quoted_text` - The caller type. Always `direct`. + - `created_at: Integer` - - `:direct` + Unix timestamp (in seconds) for when the item was created. - - `class Program` + - `inference_options: InferenceOptions{ model, tool_choice}` - - `caller_id: String` + Inference overrides applied to the message. Defaults to null when unset. - The call ID of the program item that produced this tool call. + - `model: String` - - `type: :program` + Model name that generated the response. Defaults to null when using the session default. - The caller type. Always `program`. + - `tool_choice: ToolChoice{ id}` - - `:program` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `max_output_length: Integer` + - `id: String` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Identifier of the requested tool. - - `status: :in_progress | :completed | :incomplete` + - `object: :"chatkit.thread_item"` - The status of the shell call output. + Type discriminator that is always `chatkit.thread_item`. - - `:in_progress` + - `:"chatkit.thread_item"` - - `:completed` + - `thread_id: String` - - `:incomplete` + Identifier of the parent thread. - - `class ApplyPatchCall` + - `type: :"chatkit.user_message"` - A tool call representing a request to create, delete, or update files using diff patches. + - `:"chatkit.user_message"` - - `call_id: String` + - `class ChatKitThreadAssistantMessageItem` - The unique ID of the apply patch tool call generated by the model. + Assistant-authored message within a thread. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `id: String` - The specific create, delete, or update instruction for the apply_patch tool call. + Identifier of the thread item. - - `class CreateFile` + - `content: Array[ChatKitResponseOutputText]` - Instruction for creating a new file via the apply_patch tool. + Ordered assistant response segments. - - `diff: String` + - `annotations: Array[File{ source, type} | URL{ source, type}]` - Unified diff content to apply when creating the file. + Ordered list of annotations attached to the response text. - - `path: String` + - `class File` - Path of the file to create relative to the workspace root. + Annotation that references an uploaded file. - - `type: :create_file` + - `source: Source{ filename, type}` - The operation type. Always `create_file`. + File attachment referenced by the annotation. - - `:create_file` + - `filename: String` - - `class DeleteFile` + Filename referenced by the annotation. - Instruction for deleting an existing file via the apply_patch tool. + - `type: :file` - - `path: String` + Type discriminator that is always `file`. - Path of the file to delete relative to the workspace root. + - `:file` - - `type: :delete_file` + - `type: :file` - The operation type. Always `delete_file`. + Type discriminator that is always `file` for this annotation. - - `:delete_file` + - `:file` - - `class UpdateFile` + - `class URL` - Instruction for updating an existing file via the apply_patch tool. + Annotation that references a URL. - - `diff: String` + - `source: Source{ type, url}` - Unified diff content to apply to the existing file. + URL referenced by the annotation. - - `path: String` + - `type: :url` - Path of the file to update relative to the workspace root. + Type discriminator that is always `url`. - - `type: :update_file` + - `:url` - The operation type. Always `update_file`. + - `url: String` - - `:update_file` + URL referenced by the annotation. - - `status: :in_progress | :completed` + - `type: :url` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Type discriminator that is always `url` for this annotation. - - `:in_progress` + - `:url` - - `:completed` + - `text: String` - - `type: :apply_patch_call` + Assistant generated text. - The type of the item. Always `apply_patch_call`. + - `type: :output_text` - - `:apply_patch_call` + Type discriminator that is always `output_text`. - - `id: String` + - `:output_text` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `created_at: Integer` - - `agent: Agent{ agent_name}` + Unix timestamp (in seconds) for when the item was created. - The agent that produced this item. + - `object: :"chatkit.thread_item"` - - `agent_name: String` + Type discriminator that is always `chatkit.thread_item`. - The canonical name of the agent that produced this item. + - `:"chatkit.thread_item"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `thread_id: String` - The execution context that produced this tool call. + Identifier of the parent thread. - - `class Direct` + - `type: :"chatkit.assistant_message"` - - `type: :direct` + Type discriminator that is always `chatkit.assistant_message`. - The caller type. Always `direct`. + - `:"chatkit.assistant_message"` - - `:direct` + - `class ChatKitWidgetItem` - - `class Program` + Thread item that renders a widget payload. - - `caller_id: String` + - `id: String` - The call ID of the program item that produced this tool call. + Identifier of the thread item. - - `type: :program` + - `created_at: Integer` - The caller type. Always `program`. + Unix timestamp (in seconds) for when the item was created. - - `:program` + - `object: :"chatkit.thread_item"` - - `class ApplyPatchCallOutput` + Type discriminator that is always `chatkit.thread_item`. - The streamed output emitted by an apply patch tool call. + - `:"chatkit.thread_item"` - - `call_id: String` + - `thread_id: String` - The unique ID of the apply patch tool call generated by the model. + Identifier of the parent thread. - - `status: :completed | :failed` + - `type: :"chatkit.widget"` - The status of the apply patch tool call output. One of `completed` or `failed`. + Type discriminator that is always `chatkit.widget`. - - `:completed` + - `:"chatkit.widget"` - - `:failed` + - `widget: String` - - `type: :apply_patch_call_output` + Serialized widget payload rendered in the UI. - The type of the item. Always `apply_patch_call_output`. + - `class ChatKitClientToolCall` - - `:apply_patch_call_output` + Record of a client side tool invocation initiated by the assistant. - `id: String` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Identifier of the thread item. - - `agent: Agent{ agent_name}` + - `arguments: String` - The agent that produced this item. + JSON-encoded arguments that were sent to the tool. - - `agent_name: String` + - `call_id: String` - The canonical name of the agent that produced this item. + Identifier for the client tool call. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `created_at: Integer` - The execution context that produced this tool call. + Unix timestamp (in seconds) for when the item was created. - - `class Direct` + - `name: String` - - `type: :direct` + Tool name that was invoked. - The caller type. Always `direct`. + - `object: :"chatkit.thread_item"` - - `:direct` + Type discriminator that is always `chatkit.thread_item`. - - `class Program` + - `:"chatkit.thread_item"` - - `caller_id: String` + - `output: String` - The call ID of the program item that produced this tool call. + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `type: :program` + - `status: :in_progress | :completed` - The caller type. Always `program`. + Execution status for the tool call. - - `:program` + - `:in_progress` - - `output: String` + - `:completed` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `thread_id: String` - - `class McpListTools` + Identifier of the parent thread. - A list of tools available on an MCP server. + - `type: :"chatkit.client_tool_call"` - - `id: String` + Type discriminator that is always `chatkit.client_tool_call`. - The unique ID of the list. + - `:"chatkit.client_tool_call"` - - `server_label: String` + - `class ChatKitTask` - The label of the MCP server. + Task emitted by the workflow to show progress and status updates. - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `id: String` - The tools available on the server. + Identifier of the thread item. - - `input_schema: untyped` + - `created_at: Integer` - The JSON schema describing the tool's input. + Unix timestamp (in seconds) for when the item was created. - - `name: String` + - `heading: String` - The name of the tool. + Optional heading for the task. Defaults to null when not provided. - - `annotations: untyped` + - `object: :"chatkit.thread_item"` - Additional annotations about the tool. + Type discriminator that is always `chatkit.thread_item`. - - `description: String` + - `:"chatkit.thread_item"` - The description of the tool. + - `summary: String` - - `type: :mcp_list_tools` + Optional summary that describes the task. Defaults to null when omitted. - The type of the item. Always `mcp_list_tools`. + - `task_type: :custom | :thought` - - `:mcp_list_tools` + Subtype for the task. - - `agent: Agent{ agent_name}` + - `:custom` - The agent that produced this item. + - `:thought` - - `agent_name: String` + - `thread_id: String` - The canonical name of the agent that produced this item. + Identifier of the parent thread. - - `error: String` + - `type: :"chatkit.task"` - Error message if the server could not list tools. + Type discriminator that is always `chatkit.task`. - - `class McpApprovalRequest` + - `:"chatkit.task"` - A request for human approval of a tool invocation. + - `class ChatKitTaskGroup` + + Collection of workflow tasks grouped together in the thread. - `id: String` - The unique ID of the approval request. + Identifier of the thread item. - - `arguments: String` + - `created_at: Integer` - A JSON string of arguments for the tool. + Unix timestamp (in seconds) for when the item was created. - - `name: String` + - `object: :"chatkit.thread_item"` - The name of the tool to run. + Type discriminator that is always `chatkit.thread_item`. - - `server_label: String` + - `:"chatkit.thread_item"` - The label of the MCP server making the request. + - `tasks: Array[Task{ heading, summary, type}]` - - `type: :mcp_approval_request` + Tasks included in the group. - The type of the item. Always `mcp_approval_request`. + - `heading: String` - - `:mcp_approval_request` + Optional heading for the grouped task. Defaults to null when not provided. - - `agent: Agent{ agent_name}` + - `summary: String` - The agent that produced this item. + Optional summary that describes the grouped task. Defaults to null when omitted. - - `agent_name: String` + - `type: :custom | :thought` - The canonical name of the agent that produced this item. + Subtype for the grouped task. - - `class McpApprovalResponse` + - `:custom` - A response to an MCP approval request. + - `:thought` - - `approval_request_id: String` + - `thread_id: String` - The ID of the approval request being answered. + Identifier of the parent thread. - - `approve: bool` + - `type: :"chatkit.task_group"` - Whether the request was approved. + Type discriminator that is always `chatkit.task_group`. - - `type: :mcp_approval_response` + - `:"chatkit.task_group"` - The type of the item. Always `mcp_approval_response`. +### Example - - `:mcp_approval_response` +```ruby +require "openai" - - `id: String` +openai = OpenAI::Client.new(api_key: "My API Key") - The unique ID of the approval response +page = openai.beta.chatkit.threads.list_items("cthr_123") - - `agent: Agent{ agent_name}` +puts(page) +``` - The agent that produced this item. +#### Response - - `agent_name: 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 canonical name of the agent that produced this item. +### Example - - `reason: String` +```ruby +require "openai" - Optional reason for the decision. +openai = OpenAI::Client.new - - `class McpCall` +page = openai.beta.chatkit.threads.list_items("cthr_123") - An invocation of a tool on an MCP server. +puts(page) +``` - - `id: String` +#### Response - The unique ID of the tool call. +```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" +} +``` - - `arguments: String` +## Retrieve ChatKit thread - A JSON string of the arguments passed to the tool. +`beta.chatkit.threads.retrieve(thread_id) -> ChatKitThread` - - `name: String` +**get** `/chatkit/threads/{thread_id}` - The name of the tool that was run. +Retrieve a ChatKit thread by its identifier. - - `server_label: String` +### Parameters - The label of the MCP server running the tool. +- `thread_id: String` - - `type: :mcp_call` +### Returns - The type of the item. Always `mcp_call`. +- `class ChatKitThread` - - `:mcp_call` + Represents a ChatKit thread and its current status. - - `agent: Agent{ agent_name}` + - `id: String` - The agent that produced this item. + Identifier of the thread. - - `agent_name: String` + - `created_at: Integer` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) for when the thread was created. - - `approval_request_id: String` + - `object: :"chatkit.thread"` - 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 discriminator that is always `chatkit.thread`. - - `error: String` + - `:"chatkit.thread"` - The error from the tool call, if any. + - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}` - - `output: String` + Current status for the thread. Defaults to `active` for newly created threads. - The output from the tool call. + - `class Active` - - `status: :in_progress | :completed | :incomplete | 2 more` + Indicates that a thread is active. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `type: :active` - - `:in_progress` + Status discriminator that is always `active`. - - `:completed` + - `:active` - - `:incomplete` + - `class Locked` - - `:calling` + Indicates that a thread is locked and cannot accept new input. - - `:failed` + - `reason: String` - - `class BetaResponseCustomToolCallOutput` + Reason that the thread was locked. Defaults to null when no reason is recorded. - The output of a custom tool call from your code, being sent back to the model. + - `type: :locked` - - `call_id: String` + Status discriminator that is always `locked`. - The call ID, used to map this custom tool call output to a custom tool call. + - `:locked` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class Closed` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Indicates that a thread has been closed. - - `String = String` + - `reason: String` - A string of the output of the custom tool call. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `type: :closed` - Text, image, or file output of the custom tool call. + Status discriminator that is always `closed`. - - `class BetaResponseInputText` + - `:closed` - A text input to the model. + - `title: String` - - `class BetaResponseInputImage` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `user: String` - - `class BetaResponseInputFile` + Free-form string that identifies your end user who owns the thread. - A file input to the model. +### Example - - `type: :custom_tool_call_output` +```ruby +require "openai" - The type of the custom tool call output. Always `custom_tool_call_output`. +openai = OpenAI::Client.new(api_key: "My API Key") - - `:custom_tool_call_output` +chatkit_thread = openai.beta.chatkit.threads.retrieve("cthr_123") - - `id: String` +puts(chatkit_thread) +``` - The unique ID of the custom tool call output in the OpenAI platform. +#### Response - - `agent: Agent{ agent_name}` +```json +{ + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" +} +``` - The agent that produced this item. +### Example - - `agent_name: String` +```ruby +require "openai" - The canonical name of the agent that produced this item. +openai = OpenAI::Client.new - - `caller_: Direct{ type} | Program{ caller_id, type}` +chatkit_thread = openai.beta.chatkit.threads.retrieve("cthr_123") - The execution context that produced this tool call. +puts(chatkit_thread) +``` - - `class Direct` +#### Response - - `type: :direct` +```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 caller type. Always `direct`. +## Delete ChatKit thread - - `:direct` +`beta.chatkit.threads.delete(thread_id) -> ThreadDeleteResponse` - - `class Program` +**delete** `/chatkit/threads/{thread_id}` - - `caller_id: String` +Delete a ChatKit thread along with its items and stored attachments. - The call ID of the program item that produced this tool call. +### Parameters - - `type: :program` +- `thread_id: String` - The caller type. Always `program`. +### Returns - - `:program` +- `class ThreadDeleteResponse` - - `class BetaResponseCustomToolCall` + Confirmation payload returned after deleting a thread. - A call to a custom tool created by the model. + - `id: String` - - `call_id: String` + Identifier of the deleted thread. - An identifier used to map this custom tool call to a tool call output. + - `deleted: bool` - - `input: String` + Indicates that the thread has been deleted. - The input for the custom tool call generated by the model. + - `object: :"chatkit.thread.deleted"` - - `name: String` + Type discriminator that is always `chatkit.thread.deleted`. - The name of the custom tool being called. + - `:"chatkit.thread.deleted"` - - `type: :custom_tool_call` +### Example - The type of the custom tool call. Always `custom_tool_call`. +```ruby +require "openai" - - `:custom_tool_call` +openai = OpenAI::Client.new(api_key: "My API Key") - - `id: String` +thread = openai.beta.chatkit.threads.delete("cthr_123") - The unique ID of the custom tool call in the OpenAI platform. +puts(thread) +``` - - `agent: Agent{ agent_name}` +#### Response - The agent that produced this item. +```json +{ + "id": "id", + "deleted": true, + "object": "chatkit.thread.deleted" +} +``` - - `agent_name: String` +### Example - The canonical name of the agent that produced this item. +```ruby +require "openai" - - `caller_: Direct{ type} | Program{ caller_id, type}` +openai = OpenAI::Client.new - The execution context that produced this tool call. +thread = openai.beta.chat_kit.threads.delete("cthr_123") - - `class Direct` +puts(thread) +``` - - `type: :direct` +## List ChatKit threads - - `:direct` +`beta.chatkit.threads.list(**kwargs) -> ConversationCursorPage` - - `class Program` +**get** `/chatkit/threads` - - `caller_id: String` +List ChatKit threads with optional pagination and user filters. - The call ID of the program item that produced this tool call. +### Parameters - - `type: :program` +- `after: String` - - `:program` + List items created after this thread item ID. Defaults to null for the first page. - - `namespace: String` +- `before: String` - The namespace of the custom tool being called. + List items created before this thread item ID. Defaults to null for the newest results. - - `class CompactionTrigger` +- `limit: Integer` - Compacts the current context. Must be the final input item. + Maximum number of thread items to return. Defaults to 20. - - `type: :compaction_trigger` +- `order: :asc | :desc` - The type of the item. Always `compaction_trigger`. + Sort order for results by creation time. Defaults to `desc`. - - `:compaction_trigger` + - `:asc` - - `agent: Agent{ agent_name}` + - `:desc` - The agent that produced this item. +- `user: 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 - - `class ItemReference` +- `class ChatKitThread` - An internal identifier for an item to reference. + Represents a ChatKit thread and its current status. - `id: String` - The ID of the item to reference. + Identifier of the thread. - - `agent: Agent{ agent_name}` + - `created_at: Integer` - The agent that produced this item. + Unix timestamp (in seconds) for when the thread was created. - - `agent_name: String` + - `object: :"chatkit.thread"` - The canonical name of the agent that produced this item. + Type discriminator that is always `chatkit.thread`. - - `type: :item_reference` + - `:"chatkit.thread"` - The type of item to reference. Always `item_reference`. + - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}` - - `:item_reference` + Current status for the thread. Defaults to `active` for newly created threads. - - `class Program` + - `class Active` - - `id: String` + Indicates that a thread is active. - The unique ID of this program item. + - `type: :active` - - `call_id: String` + Status discriminator that is always `active`. - The stable call ID of the program item. + - `:active` - - `code: String` + - `class Locked` - The JavaScript source executed by programmatic tool calling. + Indicates that a thread is locked and cannot accept new input. - - `fingerprint: String` + - `reason: String` - Opaque program replay fingerprint that must be round-tripped. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `type: :program` + - `type: :locked` - The item type. Always `program`. + Status discriminator that is always `locked`. - - `:program` + - `:locked` - - `agent: Agent{ agent_name}` + - `class Closed` - The agent that produced this item. + Indicates that a thread has been closed. - - `agent_name: String` + - `reason: String` - The canonical name of the agent that produced this item. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `class ProgramOutput` + - `type: :closed` - - `id: String` + Status discriminator that is always `closed`. - The unique ID of this program output item. + - `:closed` - - `call_id: String` + - `title: String` - The call ID of the program item. + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `result: String` + - `user: String` - The result produced by the program item. + Free-form string that identifies your end user who owns the thread. - - `status: :completed | :incomplete` +### Example - The terminal status of the program output. +```ruby +require "openai" - - `:completed` +openai = OpenAI::Client.new(api_key: "My API Key") - - `:incomplete` +page = openai.beta.chatkit.threads.list - - `type: :program_output` +puts(page) +``` - The item type. Always `program_output`. +#### Response - - `:program_output` +```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" +} +``` - - `agent: Agent{ agent_name}` +### Example - The agent that produced this item. +```ruby +require "openai" - - `agent_name: String` +openai = OpenAI::Client.new - The canonical name of the agent that produced this item. +page = openai.beta.chatkit.threads.list - - `metadata: Hash[Symbol, String]` +puts(page) +``` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. +#### Response - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. +```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" +} +``` - - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` +## Domain Types - 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. +### Chat Session - - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` +- `class ChatSession` - 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. + Represents a ChatKit session and its resolved configuration. - - `:"gpt-5.6-sol"` + - `id: String` - - `:"gpt-5.6-terra"` + Identifier for the ChatKit session. - - `:"gpt-5.6-luna"` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - - `:"gpt-5.4"` + Resolved ChatKit feature configuration for the session. - - `:"gpt-5.4-mini"` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `:"gpt-5.4-nano"` + Automatic thread titling preferences. - - `:"gpt-5.4-mini-2026-03-17"` + - `enabled: bool` - - `:"gpt-5.4-nano-2026-03-17"` + Whether automatic thread titling is enabled. - - `:"gpt-5.3-chat-latest"` + - `file_upload: ChatSessionFileUpload` - - `:"gpt-5.2"` + Upload settings for the session. - - `:"gpt-5.2-2025-12-11"` + - `enabled: bool` - - `:"gpt-5.2-chat-latest"` + Indicates if uploads are enabled for the session. - - `:"gpt-5.2-pro"` + - `max_file_size: Integer` - - `:"gpt-5.2-pro-2025-12-11"` + Maximum upload size in megabytes. - - `:"gpt-5.1"` + - `max_files: Integer` - - `:"gpt-5.1-2025-11-13"` + Maximum number of uploads allowed during the session. - - `:"gpt-5.1-codex"` + - `history: ChatSessionHistory` - - `:"gpt-5.1-mini"` + History retention configuration. - - `:"gpt-5.1-chat-latest"` + - `enabled: bool` - - `:"gpt-5"` + Indicates if chat history is persisted for the session. - - `:"gpt-5-mini"` + - `recent_threads: Integer` - - `:"gpt-5-nano"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `:"gpt-5-2025-08-07"` + - `client_secret: String` - - `:"gpt-5-mini-2025-08-07"` + Ephemeral client secret that authenticates session requests. - - `:"gpt-5-nano-2025-08-07"` + - `expires_at: Integer` - - `:"gpt-5-chat-latest"` + Unix timestamp (in seconds) for when the session expires. - - `:"gpt-4.1"` + - `max_requests_per_1_minute: Integer` - - `:"gpt-4.1-mini"` + Convenience copy of the per-minute request limit. - - `:"gpt-4.1-nano"` + - `object: :"chatkit.session"` - - `:"gpt-4.1-2025-04-14"` + Type discriminator that is always `chatkit.session`. - - `:"gpt-4.1-mini-2025-04-14"` + - `:"chatkit.session"` - - `:"gpt-4.1-nano-2025-04-14"` + - `rate_limits: ChatSessionRateLimits` - - `:"o4-mini"` + Resolved rate limit values. - - `:"o4-mini-2025-04-16"` + - `max_requests_per_1_minute: Integer` - - `:o3` + Maximum allowed requests per one-minute window. - - `:"o3-2025-04-16"` + - `status: ChatSessionStatus` - - `:"o3-mini"` + Current lifecycle state of the session. - - `:"o3-mini-2025-01-31"` + - `:active` - - `:o1` + - `:expired` - - `:"o1-2024-12-17"` + - `:cancelled` - - `:"o1-preview"` + - `user: String` - - `:"o1-preview-2024-09-12"` + User identifier associated with the session. - - `:"o1-mini"` + - `workflow: ChatKitWorkflow` - - `:"o1-mini-2024-09-12"` + Workflow metadata for the session. - - `:"gpt-4o"` + - `id: String` - - `:"gpt-4o-2024-11-20"` + Identifier of the workflow backing the session. - - `:"gpt-4o-2024-08-06"` + - `state_variables: Hash[Symbol, String | bool | Float]` - - `:"gpt-4o-2024-05-13"` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `:"gpt-4o-audio-preview"` + - `String = String` - - `:"gpt-4o-audio-preview-2024-10-01"` + - `UnionMember1 = bool` - - `:"gpt-4o-audio-preview-2024-12-17"` + - `Float = Float` - - `:"gpt-4o-audio-preview-2025-06-03"` + - `tracing: Tracing{ enabled}` - - `:"gpt-4o-mini-audio-preview"` + Tracing settings applied to the workflow. - - `:"gpt-4o-mini-audio-preview-2024-12-17"` + - `enabled: bool` - - `:"gpt-4o-search-preview"` + Indicates whether tracing is enabled. - - `:"gpt-4o-mini-search-preview"` + - `version: String` - - `:"gpt-4o-search-preview-2025-03-11"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `:"gpt-4o-mini-search-preview-2025-03-11"` +### Chat Session Automatic Thread Titling - - `:"chatgpt-4o-latest"` +- `class ChatSessionAutomaticThreadTitling` - - `:"codex-mini-latest"` + Automatic thread title preferences for the session. - - `:"gpt-4o-mini"` + - `enabled: bool` - - `:"gpt-4o-mini-2024-07-18"` + Whether automatic thread titling is enabled. - - `:"gpt-4-turbo"` +### Chat Session ChatKit Configuration - - `:"gpt-4-turbo-2024-04-09"` +- `class ChatSessionChatKitConfiguration` - - `:"gpt-4-0125-preview"` + ChatKit configuration for the session. - - `:"gpt-4-turbo-preview"` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `:"gpt-4-1106-preview"` + Automatic thread titling preferences. - - `:"gpt-4-vision-preview"` + - `enabled: bool` - - `:"gpt-4"` + Whether automatic thread titling is enabled. - - `:"gpt-4-0314"` + - `file_upload: ChatSessionFileUpload` - - `:"gpt-4-0613"` + Upload settings for the session. - - `:"gpt-4-32k"` + - `enabled: bool` - - `:"gpt-4-32k-0314"` + Indicates if uploads are enabled for the session. - - `:"gpt-4-32k-0613"` + - `max_file_size: Integer` - - `:"gpt-3.5-turbo"` + Maximum upload size in megabytes. - - `:"gpt-3.5-turbo-16k"` + - `max_files: Integer` - - `:"gpt-3.5-turbo-0301"` + Maximum number of uploads allowed during the session. - - `:"gpt-3.5-turbo-0613"` + - `history: ChatSessionHistory` - - `:"gpt-3.5-turbo-1106"` + History retention configuration. - - `:"gpt-3.5-turbo-0125"` + - `enabled: bool` - - `:"gpt-3.5-turbo-16k-0613"` + Indicates if chat history is persisted for the session. - - `:"o1-pro"` + - `recent_threads: Integer` - - `:"o1-pro-2025-03-19"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `:"o3-pro"` +### Chat Session ChatKit Configuration Param - - `:"o3-pro-2025-06-10"` +- `class ChatSessionChatKitConfigurationParam` - - `:"o3-deep-research"` + Optional per-session configuration settings for ChatKit behavior. - - `:"o3-deep-research-2025-06-26"` + - `automatic_thread_titling: AutomaticThreadTitling{ enabled}` - - `:"o4-mini-deep-research"` + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `:"o4-mini-deep-research-2025-06-26"` + - `enabled: bool` - - `:"computer-use-preview"` + Enable automatic thread title generation. Defaults to true. - - `:"computer-use-preview-2025-03-11"` + - `file_upload: FileUpload{ enabled, max_file_size, max_files}` - - `:"gpt-5-codex"` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - `:"gpt-5-pro"` + - `enabled: bool` - - `:"gpt-5-pro-2025-10-06"` + Enable uploads for this session. Defaults to false. - - `:"gpt-5.1-codex-max"` + - `max_file_size: Integer` - - `String = String` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `object: :response` + - `max_files: Integer` - The object type of this resource - always set to `response`. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `:response` + - `history: History{ enabled, recent_threads}` - - `output: Array[BetaResponseOutputItem]` + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - An array of content items generated by the model. + - `enabled: bool` - - 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. + Enables chat users to access previous ChatKit threads. Defaults to true. - - `class BetaResponseOutputMessage` + - `recent_threads: Integer` - An output message from the model. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `class BetaResponseFileSearchToolCall` +### Chat Session Expires After Param - 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. +- `class ChatSessionExpiresAfterParam` - - `class BetaResponseFunctionToolCall` + Controls when the session expires relative to an anchor timestamp. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `anchor: :created_at` - - `class BetaResponseFunctionToolCallOutputItem` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - - `id: String` + - `:created_at` - The unique ID of the function call tool output. + - `seconds: Integer` - - `call_id: String` + Number of seconds after the anchor when the session expires. - The unique ID of the function tool call generated by the model. +### Chat Session File Upload - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` +- `class ChatSessionFileUpload` - The output from the function call generated by your code. - Can be a string or an list of output content. + Upload permissions and limits applied to the session. - - `String = String` + - `enabled: bool` - A string of the output of the function call. + Indicates if uploads are enabled for the session. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `max_file_size: Integer` - Text, image, or file output of the function call. + Maximum upload size in megabytes. - - `class BetaResponseInputText` + - `max_files: Integer` - A text input to the model. + Maximum number of uploads allowed during the session. - - `class BetaResponseInputImage` +### Chat Session History - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). +- `class ChatSessionHistory` - - `class BetaResponseInputFile` + History retention preferences returned for the session. - A file input to the model. + - `enabled: bool` - - `status: :in_progress | :completed | :incomplete` + Indicates if chat history is persisted for the session. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `recent_threads: Integer` - - `:in_progress` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `:completed` +### Chat Session Rate Limits - - `:incomplete` +- `class ChatSessionRateLimits` - - `type: :function_call_output` + Active per-minute request limit for the session. - The type of the function tool call output. Always `function_call_output`. + - `max_requests_per_1_minute: Integer` - - `:function_call_output` + Maximum allowed requests per one-minute window. - - `agent: Agent{ agent_name}` +### Chat Session Rate Limits Param - The agent that produced this item. +- `class ChatSessionRateLimitsParam` - - `agent_name: String` + Controls request rate limits for the session. - The canonical name of the agent that produced this item. + - `max_requests_per_1_minute: Integer` - - `caller_: Direct{ type} | Program{ caller_id, type}` + Maximum number of requests allowed per minute for the session. Defaults to 10. - The execution context that produced this tool call. +### Chat Session Status - - `class Direct` +- `ChatSessionStatus = :active | :expired | :cancelled` - - `type: :direct` + - `:active` - The caller type. Always `direct`. + - `:expired` - - `:direct` + - `:cancelled` - - `class Program` +### Chat Session Workflow Param - - `caller_id: String` +- `class ChatSessionWorkflowParam` - The call ID of the program item that produced this tool call. + Workflow reference and overrides applied to the chat session. - - `type: :program` + - `id: String` - The caller type. Always `program`. + Identifier for the workflow invoked by the session. - - `:program` + - `state_variables: Hash[Symbol, String | bool | Float]` - - `created_by: String` + 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 identifier of the actor that created the item. + - `String = String` - - `class AgentMessage` + - `UnionMember1 = bool` - - `id: String` + - `Float = Float` - The unique ID of the agent message. + - `tracing: Tracing{ enabled}` - - `author: String` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - The sending agent identity. + - `enabled: bool` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + Whether tracing is enabled during the session. Defaults to true. - Encrypted content sent between agents. + - `version: String` - - `class BetaResponseInputText` + Specific workflow version to run. Defaults to the latest deployed version. - A text input to the model. +### ChatKit Attachment - - `class BetaResponseOutputText` +- `class ChatKitAttachment` - A text output from the model. + Attachment metadata included on thread items. - - `class Text` + - `id: String` - A text content. + Identifier for the attachment. - - `text: String` + - `mime_type: String` - - `type: :text` + MIME type of the attachment. - - `:text` + - `name: String` - - `class SummaryText` + Original display name for the attachment. - A summary text from the model. + - `preview_url: String` - - `text: String` + Preview URL for rendering the attachment inline. - A summary of the reasoning output from the model so far. + - `type: :image | :file` - - `type: :summary_text` + Attachment discriminator. - The type of the object. Always `summary_text`. + - `:image` - - `:summary_text` + - `:file` - - `class ReasoningText` +### ChatKit Response Output Text - Reasoning text from the model. +- `class ChatKitResponseOutputText` - - `text: String` + Assistant response text accompanied by optional annotations. - The reasoning text from the model. + - `annotations: Array[File{ source, type} | URL{ source, type}]` - - `type: :reasoning_text` + Ordered list of annotations attached to the response text. - The type of the reasoning text. Always `reasoning_text`. + - `class File` - - `:reasoning_text` + Annotation that references an uploaded file. - - `class BetaResponseOutputRefusal` + - `source: Source{ filename, type}` - A refusal from the model. + File attachment referenced by the annotation. - - `class BetaResponseInputImage` + - `filename: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Filename referenced by the annotation. - - `class ComputerScreenshot` + - `type: :file` - A screenshot of a computer. + Type discriminator that is always `file`. - - `detail: :low | :high | :auto | :original` + - `:file` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: :file` - - `:low` + Type discriminator that is always `file` for this annotation. - - `:high` + - `:file` - - `:auto` + - `class URL` - - `:original` + Annotation that references a URL. - - `file_id: String` + - `source: Source{ type, url}` - The identifier of an uploaded file that contains the screenshot. + URL referenced by the annotation. - - `image_url: String` + - `type: :url` - The URL of the screenshot image. + Type discriminator that is always `url`. - - `type: :computer_screenshot` + - `:url` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `url: String` - - `:computer_screenshot` + URL referenced by the annotation. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `type: :url` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Type discriminator that is always `url` for this annotation. - - `mode: :explicit` + - `:url` - The breakpoint mode. Always `explicit`. + - `text: String` - - `:explicit` + Assistant generated text. - - `class BetaResponseInputFile` + - `type: :output_text` - A file input to the model. + Type discriminator that is always `output_text`. - - `class EncryptedContent` + - `:output_text` - Opaque encrypted content that Responses API decrypts inside trusted model execution. +### ChatKit Thread - - `encrypted_content: String` +- `class ChatKitThread` - Opaque encrypted content. + Represents a ChatKit thread and its current status. - - `type: :encrypted_content` + - `id: String` - The type of the input item. Always `encrypted_content`. + Identifier of the thread. - - `:encrypted_content` + - `created_at: Integer` - - `recipient: String` + Unix timestamp (in seconds) for when the thread was created. - The destination agent identity. + - `object: :"chatkit.thread"` - - `type: :agent_message` + Type discriminator that is always `chatkit.thread`. - The type of the item. Always `agent_message`. + - `:"chatkit.thread"` - - `:agent_message` + - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}` - - `agent: Agent{ agent_name}` + Current status for the thread. Defaults to `active` for newly created threads. - The agent that produced this item. + - `class Active` - - `agent_name: String` + Indicates that a thread is active. - The canonical name of the agent that produced this item. + - `type: :active` - - `class MultiAgentCall` + Status discriminator that is always `active`. - - `id: String` + - `:active` - The unique ID of the multi-agent call item. + - `class Locked` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + Indicates that a thread is locked and cannot accept new input. - The multi-agent action to execute. + - `reason: String` - - `:spawn_agent` + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `:interrupt_agent` + - `type: :locked` - - `:list_agents` + Status discriminator that is always `locked`. - - `:send_message` + - `:locked` - - `:followup_task` + - `class Closed` - - `:wait_agent` + Indicates that a thread has been closed. - - `arguments: String` + - `reason: String` - The JSON string of arguments generated for the action. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `call_id: String` + - `type: :closed` - The unique ID linking this call to its output. + Status discriminator that is always `closed`. - - `type: :multi_agent_call` + - `:closed` - The type of the multi-agent call. Always `multi_agent_call`. + - `title: String` - - `:multi_agent_call` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `agent: Agent{ agent_name}` + - `user: String` - The agent that produced this item. + Free-form string that identifies your end user who owns the thread. - - `agent_name: String` +### ChatKit Thread Assistant Message Item - The canonical name of the agent that produced this item. +- `class ChatKitThreadAssistantMessageItem` - - `class MultiAgentCallOutput` + Assistant-authored message within a thread. - `id: String` - The unique ID of the multi-agent call output item. - - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - - The multi-agent action that produced this result. - - - `:spawn_agent` + Identifier of the thread item. - - `:interrupt_agent` + - `content: Array[ChatKitResponseOutputText]` - - `:list_agents` + Ordered assistant response segments. - - `:send_message` + - `annotations: Array[File{ source, type} | URL{ source, type}]` - - `:followup_task` + Ordered list of annotations attached to the response text. - - `:wait_agent` + - `class File` - - `call_id: String` + Annotation that references an uploaded file. - The unique ID of the multi-agent call. + - `source: Source{ filename, type}` - - `output: Array[BetaResponseOutputText]` + File attachment referenced by the annotation. - Text output returned by the multi-agent action. + - `filename: String` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + Filename referenced by the annotation. - The annotations of the text output. + - `type: :file` - - `text: String` + Type discriminator that is always `file`. - The text output from the model. + - `:file` - - `type: :output_text` + - `type: :file` - The type of the output text. Always `output_text`. + Type discriminator that is always `file` for this annotation. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:file` - - `type: :multi_agent_call_output` + - `class URL` - The type of the multi-agent result. Always `multi_agent_call_output`. + Annotation that references a URL. - - `:multi_agent_call_output` + - `source: Source{ type, url}` - - `agent: Agent{ agent_name}` + URL referenced by the annotation. - The agent that produced this item. + - `type: :url` - - `agent_name: String` + Type discriminator that is always `url`. - The canonical name of the agent that produced this item. + - `:url` - - `class BetaResponseFunctionWebSearch` + - `url: 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. + URL referenced by the annotation. - - `class BetaResponseComputerToolCall` + - `type: :url` - 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 discriminator that is always `url` for this annotation. - - `class BetaResponseComputerToolCallOutputItem` + - `:url` - - `id: String` + - `text: String` - The unique ID of the computer call tool output. + Assistant generated text. - - `call_id: String` + - `type: :output_text` - The ID of the computer tool call that produced the output. + Type discriminator that is always `output_text`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `:output_text` - A computer screenshot image used with the computer use tool. + - `created_at: Integer` - - `status: :completed | :incomplete | :failed | :in_progress` + Unix timestamp (in seconds) for when the item was created. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `object: :"chatkit.thread_item"` - - `:completed` + Type discriminator that is always `chatkit.thread_item`. - - `:incomplete` + - `:"chatkit.thread_item"` - - `:failed` + - `thread_id: String` - - `:in_progress` + Identifier of the parent thread. - - `type: :computer_call_output` + - `type: :"chatkit.assistant_message"` - The type of the computer tool call output. Always `computer_call_output`. + Type discriminator that is always `chatkit.assistant_message`. - - `:computer_call_output` + - `:"chatkit.assistant_message"` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` +### ChatKit Thread Item List - The safety checks reported by the API that have been acknowledged by the - developer. +- `class ChatKitThreadItemList` - - `id: String` + A paginated list of thread items rendered for the ChatKit API. - The ID of the pending safety check. + - `data: Array[ChatKitThreadUserMessageItem | ChatKitThreadAssistantMessageItem | ChatKitWidgetItem | 3 more]` - - `code: String` + A list of items - The type of the pending safety check. + - `class ChatKitThreadUserMessageItem` - - `message: String` + User-authored messages within a thread. - Details about the pending safety check. + - `id: String` - - `agent: Agent{ agent_name}` + Identifier of the thread item. - The agent that produced this item. + - `attachments: Array[ChatKitAttachment]` - - `agent_name: String` + Attachments associated with the user message. Defaults to an empty list. - The canonical name of the agent that produced this item. + - `id: String` - - `created_by: String` + Identifier for the attachment. - The identifier of the actor that created the item. + - `mime_type: String` - - `class BetaResponseReasoningItem` + MIME type of the attachment. - 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). + - `name: String` - - `class Program` + Original display name for the attachment. - - `id: String` + - `preview_url: String` - The unique ID of the program item. + Preview URL for rendering the attachment inline. - - `call_id: String` + - `type: :image | :file` - The stable call ID of the program item. + Attachment discriminator. - - `code: String` + - `:image` - The JavaScript source executed by programmatic tool calling. + - `:file` - - `fingerprint: String` + - `content: Array[InputText{ text, type} | QuotedText{ text, type}]` - Opaque program replay fingerprint that must be round-tripped. + Ordered content elements supplied by the user. - - `type: :program` + - `class InputText` - The type of the item. Always `program`. + Text block that a user contributed to the thread. - - `:program` + - `text: String` - - `agent: Agent{ agent_name}` + Plain-text content supplied by the user. - The agent that produced this item. + - `type: :input_text` - - `agent_name: String` + Type discriminator that is always `input_text`. - The canonical name of the agent that produced this item. + - `:input_text` - - `class ProgramOutput` + - `class QuotedText` - - `id: String` + Quoted snippet that the user referenced in their message. - The unique ID of the program output item. + - `text: String` - - `call_id: String` + Quoted text content. - The call ID of the program item. + - `type: :quoted_text` - - `result: String` + Type discriminator that is always `quoted_text`. - The result produced by the program item. + - `:quoted_text` - - `status: :completed | :incomplete` + - `created_at: Integer` - The terminal status of the program output item. + Unix timestamp (in seconds) for when the item was created. - - `:completed` + - `inference_options: InferenceOptions{ model, tool_choice}` - - `:incomplete` + Inference overrides applied to the message. Defaults to null when unset. - - `type: :program_output` + - `model: String` - The type of the item. Always `program_output`. + Model name that generated the response. Defaults to null when using the session default. - - `:program_output` + - `tool_choice: ToolChoice{ id}` - - `agent: Agent{ agent_name}` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - The agent that produced this item. + - `id: String` - - `agent_name: String` + Identifier of the requested tool. - The canonical name of the agent that produced this item. + - `object: :"chatkit.thread_item"` - - `class BetaResponseToolSearchCall` + Type discriminator that is always `chatkit.thread_item`. - - `id: String` + - `:"chatkit.thread_item"` - The unique ID of the tool search call item. + - `thread_id: String` - - `arguments: untyped` + Identifier of the parent thread. - Arguments used for the tool search call. + - `type: :"chatkit.user_message"` - - `call_id: String` + - `:"chatkit.user_message"` - The unique ID of the tool search call generated by the model. + - `class ChatKitThreadAssistantMessageItem` - - `execution: :server | :client` + Assistant-authored message within a thread. - Whether tool search was executed by the server or by the client. + - `id: String` - - `:server` + Identifier of the thread item. - - `:client` + - `content: Array[ChatKitResponseOutputText]` - - `status: :in_progress | :completed | :incomplete` + Ordered assistant response segments. - The status of the tool search call item that was recorded. + - `annotations: Array[File{ source, type} | URL{ source, type}]` - - `:in_progress` + Ordered list of annotations attached to the response text. - - `:completed` + - `class File` - - `:incomplete` + Annotation that references an uploaded file. - - `type: :tool_search_call` + - `source: Source{ filename, type}` - The type of the item. Always `tool_search_call`. + File attachment referenced by the annotation. - - `:tool_search_call` + - `filename: String` - - `agent: Agent{ agent_name}` + Filename referenced by the annotation. - The agent that produced this item. + - `type: :file` - - `agent_name: String` + Type discriminator that is always `file`. - The canonical name of the agent that produced this item. + - `:file` - - `created_by: String` + - `type: :file` - The identifier of the actor that created the item. + Type discriminator that is always `file` for this annotation. - - `class BetaResponseToolSearchOutputItem` + - `:file` - - `id: String` + - `class URL` - The unique ID of the tool search output item. + Annotation that references a URL. - - `call_id: String` + - `source: Source{ type, url}` - The unique ID of the tool search call generated by the model. + URL referenced by the annotation. - - `execution: :server | :client` + - `type: :url` - Whether tool search was executed by the server or by the client. + Type discriminator that is always `url`. - - `:server` + - `:url` - - `:client` + - `url: String` - - `status: :in_progress | :completed | :incomplete` + URL referenced by the annotation. - The status of the tool search output item that was recorded. + - `type: :url` - - `:in_progress` + Type discriminator that is always `url` for this annotation. - - `:completed` + - `:url` - - `:incomplete` + - `text: String` - - `tools: Array[BetaTool]` + Assistant generated text. - The loaded tool definitions returned by tool search. + - `type: :output_text` - - `class BetaFunctionTool` + Type discriminator that is always `output_text`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `:output_text` - - `class BetaFileSearchTool` + - `created_at: Integer` - 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). + Unix timestamp (in seconds) for when the item was created. - - `class BetaComputerTool` + - `object: :"chatkit.thread_item"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Type discriminator that is always `chatkit.thread_item`. - - `class BetaComputerUsePreviewTool` + - `:"chatkit.thread_item"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `thread_id: String` - - `class BetaWebSearchTool` + Identifier of the parent thread. - 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: :"chatkit.assistant_message"` - - `class Mcp` + Type discriminator that is always `chatkit.assistant_message`. - 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). + - `:"chatkit.assistant_message"` - - `class CodeInterpreter` + - `class ChatKitWidgetItem` - A tool that runs Python code to help generate a response to a prompt. + Thread item that renders a widget payload. - - `class ProgrammaticToolCalling` + - `id: String` - - `class ImageGeneration` + Identifier of the thread item. - A tool that generates images using the GPT image models. + - `created_at: Integer` - - `class LocalShell` + Unix timestamp (in seconds) for when the item was created. - A tool that allows the model to execute shell commands in a local environment. + - `object: :"chatkit.thread_item"` - - `class BetaFunctionShellTool` + Type discriminator that is always `chatkit.thread_item`. - A tool that allows the model to execute shell commands. + - `:"chatkit.thread_item"` - - `class BetaCustomTool` + - `thread_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) + Identifier of the parent thread. - - `class BetaNamespaceTool` + - `type: :"chatkit.widget"` - Groups function/custom tools under a shared namespace. + Type discriminator that is always `chatkit.widget`. - - `class BetaToolSearchTool` + - `:"chatkit.widget"` - Hosted or BYOT tool search configuration for deferred tools. + - `widget: String` - - `class BetaWebSearchPreviewTool` + Serialized widget payload rendered in the UI. - 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). + - `class ChatKitClientToolCall` - - `class BetaApplyPatchTool` + Record of a client side tool invocation initiated by the assistant. - Allows the assistant to create, delete, or update files using unified diffs. + - `id: String` - - `type: :tool_search_output` + Identifier of the thread item. - The type of the item. Always `tool_search_output`. + - `arguments: String` - - `:tool_search_output` + JSON-encoded arguments that were sent to the tool. - - `agent: Agent{ agent_name}` + - `call_id: String` - The agent that produced this item. + Identifier for the client tool call. - - `agent_name: String` + - `created_at: Integer` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) for when the item was created. - - `created_by: String` + - `name: String` - The identifier of the actor that created the item. + Tool name that was invoked. - - `class AdditionalTools` + - `object: :"chatkit.thread_item"` - - `id: String` + Type discriminator that is always `chatkit.thread_item`. - The unique ID of the additional tools item. + - `:"chatkit.thread_item"` - - `role: :unknown | :user | :assistant | 5 more` + - `output: String` - The role that provided the additional tools. + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `:unknown` + - `status: :in_progress | :completed` - - `:user` + Execution status for the tool call. - - `:assistant` + - `:in_progress` - - `:system` + - `:completed` - - `:critic` + - `thread_id: String` - - `:discriminator` + Identifier of the parent thread. - - `:developer` + - `type: :"chatkit.client_tool_call"` - - `:tool` + Type discriminator that is always `chatkit.client_tool_call`. - - `tools: Array[BetaTool]` + - `:"chatkit.client_tool_call"` - The additional tool definitions made available at this item. + - `class ChatKitTask` - - `class BetaFunctionTool` + Task emitted by the workflow to show progress and status updates. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `id: String` - - `class BetaFileSearchTool` + Identifier of the thread 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_at: Integer` - - `class BetaComputerTool` + Unix timestamp (in seconds) for when the item was created. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `heading: String` - - `class BetaComputerUsePreviewTool` + Optional heading for the task. Defaults to null when not provided. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `object: :"chatkit.thread_item"` - - `class BetaWebSearchTool` + Type discriminator that is always `chatkit.thread_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). + - `:"chatkit.thread_item"` - - `class Mcp` + - `summary: 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). + Optional summary that describes the task. Defaults to null when omitted. - - `class CodeInterpreter` + - `task_type: :custom | :thought` - A tool that runs Python code to help generate a response to a prompt. + Subtype for the task. - - `class ProgrammaticToolCalling` + - `:custom` - - `class ImageGeneration` + - `:thought` - A tool that generates images using the GPT image models. + - `thread_id: String` - - `class LocalShell` + Identifier of the parent thread. - A tool that allows the model to execute shell commands in a local environment. + - `type: :"chatkit.task"` - - `class BetaFunctionShellTool` + Type discriminator that is always `chatkit.task`. - A tool that allows the model to execute shell commands. + - `:"chatkit.task"` - - `class BetaCustomTool` + - `class ChatKitTaskGroup` - 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) + Collection of workflow tasks grouped together in the thread. - - `class BetaNamespaceTool` + - `id: String` - Groups function/custom tools under a shared namespace. + Identifier of the thread item. - - `class BetaToolSearchTool` + - `created_at: Integer` - Hosted or BYOT tool search configuration for deferred tools. + Unix timestamp (in seconds) for when the item was created. - - `class BetaWebSearchPreviewTool` + - `object: :"chatkit.thread_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 discriminator that is always `chatkit.thread_item`. - - `class BetaApplyPatchTool` + - `:"chatkit.thread_item"` - Allows the assistant to create, delete, or update files using unified diffs. + - `tasks: Array[Task{ heading, summary, type}]` - - `type: :additional_tools` + Tasks included in the group. - The type of the item. Always `additional_tools`. + - `heading: String` - - `:additional_tools` + Optional heading for the grouped task. Defaults to null when not provided. - - `agent: Agent{ agent_name}` + - `summary: String` - The agent that produced this item. + Optional summary that describes the grouped task. Defaults to null when omitted. - - `agent_name: String` + - `type: :custom | :thought` - The canonical name of the agent that produced this item. + Subtype for the grouped task. - - `class BetaResponseCompactionItem` + - `:custom` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `:thought` - - `id: String` + - `thread_id: String` - The unique ID of the compaction item. + Identifier of the parent thread. - - `encrypted_content: String` + - `type: :"chatkit.task_group"` - The encrypted content that was produced by compaction. + Type discriminator that is always `chatkit.task_group`. - - `type: :compaction` + - `:"chatkit.task_group"` - The type of the item. Always `compaction`. + - `first_id: String` - - `:compaction` + The ID of the first item in the list. - - `agent: Agent{ agent_name}` + - `has_more: bool` - The agent that produced this item. + Whether there are more items available. - - `agent_name: String` + - `last_id: String` - The canonical name of the agent that produced this item. + The ID of the last item in the list. - - `created_by: String` + - `object: :list` - The identifier of the actor that created the item. + The type of object returned, must be `list`. - - `class ImageGenerationCall` + - `:list` - An image generation request made by the model. +### ChatKit Thread User Message Item - - `id: String` +- `class ChatKitThreadUserMessageItem` - The unique ID of the image generation call. + User-authored messages within a thread. - - `result: String` + - `id: String` - The generated image encoded in base64. + Identifier of the thread item. - - `status: :in_progress | :completed | :generating | :failed` + - `attachments: Array[ChatKitAttachment]` - The status of the image generation call. + Attachments associated with the user message. Defaults to an empty list. - - `:in_progress` + - `id: String` - - `:completed` + Identifier for the attachment. - - `:generating` + - `mime_type: String` - - `:failed` + MIME type of the attachment. - - `type: :image_generation_call` + - `name: String` - The type of the image generation call. Always `image_generation_call`. + Original display name for the attachment. - - `:image_generation_call` + - `preview_url: String` - - `agent: Agent{ agent_name}` + Preview URL for rendering the attachment inline. - The agent that produced this item. + - `type: :image | :file` - - `agent_name: String` + Attachment discriminator. - The canonical name of the agent that produced this item. + - `:image` - - `class BetaResponseCodeInterpreterToolCall` + - `:file` - A tool call to run code. + - `content: Array[InputText{ text, type} | QuotedText{ text, type}]` - - `class LocalShellCall` + Ordered content elements supplied by the user. - A tool call to run a command on the local shell. + - `class InputText` - - `id: String` + Text block that a user contributed to the thread. - The unique ID of the local shell call. + - `text: String` - - `action: Action{ command, env, type, 3 more}` + Plain-text content supplied by the user. - Execute a shell command on the server. + - `type: :input_text` - - `command: Array[String]` + Type discriminator that is always `input_text`. - The command to run. + - `:input_text` - - `env: Hash[Symbol, String]` + - `class QuotedText` - Environment variables to set for the command. + Quoted snippet that the user referenced in their message. - - `type: :exec` + - `text: String` - The type of the local shell action. Always `exec`. + Quoted text content. - - `:exec` + - `type: :quoted_text` - - `timeout_ms: Integer` + Type discriminator that is always `quoted_text`. - Optional timeout in milliseconds for the command. + - `:quoted_text` - - `user: String` + - `created_at: Integer` - Optional user to run the command as. + Unix timestamp (in seconds) for when the item was created. - - `working_directory: String` + - `inference_options: InferenceOptions{ model, tool_choice}` - Optional working directory to run the command in. + Inference overrides applied to the message. Defaults to null when unset. - - `call_id: String` + - `model: String` - The unique ID of the local shell tool call generated by the model. + Model name that generated the response. Defaults to null when using the session default. - - `status: :in_progress | :completed | :incomplete` + - `tool_choice: ToolChoice{ id}` - The status of the local shell call. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `:in_progress` + - `id: String` - - `:completed` + Identifier of the requested tool. - - `:incomplete` + - `object: :"chatkit.thread_item"` - - `type: :local_shell_call` + Type discriminator that is always `chatkit.thread_item`. - The type of the local shell call. Always `local_shell_call`. + - `:"chatkit.thread_item"` - - `:local_shell_call` + - `thread_id: String` - - `agent: Agent{ agent_name}` + Identifier of the parent thread. - The agent that produced this item. + - `type: :"chatkit.user_message"` - - `agent_name: String` + - `:"chatkit.user_message"` - The canonical name of the agent that produced this item. +### ChatKit Widget Item - - `class LocalShellCallOutput` +- `class ChatKitWidgetItem` - The output of a local shell tool call. + Thread item that renders a widget payload. - `id: String` - The unique ID of the local shell tool call generated by the model. - - - `output: String` + Identifier of the thread item. - A JSON string of the output of the local shell tool call. + - `created_at: Integer` - - `type: :local_shell_call_output` + Unix timestamp (in seconds) for when the item was created. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `object: :"chatkit.thread_item"` - - `:local_shell_call_output` + Type discriminator that is always `chatkit.thread_item`. - - `agent: Agent{ agent_name}` + - `:"chatkit.thread_item"` - The agent that produced this item. + - `thread_id: String` - - `agent_name: String` + Identifier of the parent thread. - The canonical name of the agent that produced this item. + - `type: :"chatkit.widget"` - - `status: :in_progress | :completed | :incomplete` + Type discriminator that is always `chatkit.widget`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `:"chatkit.widget"` - - `:in_progress` + - `widget: String` - - `:completed` + Serialized widget payload rendered in the UI. - - `:incomplete` +### Thread Delete Response - - `class BetaResponseFunctionShellToolCall` +- `class ThreadDeleteResponse` - A tool call that executes one or more shell commands in a managed environment. + Confirmation payload returned after deleting a thread. - `id: String` - The unique ID of the shell tool call. Populated when this item is returned via API. + Identifier of the deleted thread. - - `action: Action{ commands, max_output_length, timeout_ms}` + - `deleted: bool` - The shell commands and limits that describe how to run the tool call. + Indicates that the thread has been deleted. - - `commands: Array[String]` + - `object: :"chatkit.thread.deleted"` - - `max_output_length: Integer` + Type discriminator that is always `chatkit.thread.deleted`. - Optional maximum number of characters to return from each command. + - `:"chatkit.thread.deleted"` - - `timeout_ms: Integer` +# Assistants - Optional timeout in milliseconds for the commands. +## List assistants - - `call_id: String` +`beta.assistants.list(**kwargs) -> CursorPage` - The unique ID of the shell tool call generated by the model. +**get** `/assistants` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` +Returns a list of assistants. - Represents the use of a local environment to perform shell actions. +### Parameters - - `class BetaResponseLocalEnvironment` +- `after: String` - Represents the use of a local environment to perform shell actions. + 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. - - `type: :local` +- `before: String` - The environment type. Always `local`. + 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. - - `:local` +- `limit: Integer` - - `class BetaResponseContainerReference` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - Represents a container created with /v1/containers. +- `order: :asc | :desc` - - `container_id: String` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `type: :container_reference` + - `:asc` - The environment type. Always `container_reference`. + - `:desc` - - `:container_reference` +### Returns - - `status: :in_progress | :completed | :incomplete` +- `class Assistant` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Represents an `assistant` that can call the model and use tools. - - `:in_progress` + - `id: String` - - `:completed` + The identifier, which can be referenced in API endpoints. - - `:incomplete` + - `created_at: Integer` - - `type: :shell_call` + The Unix timestamp (in seconds) for when the assistant was created. - The type of the item. Always `shell_call`. + - `description: String` - - `:shell_call` + The description of the assistant. The maximum length is 512 characters. - - `agent: Agent{ agent_name}` + - `instructions: String` - The agent that produced this item. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `agent_name: String` + - `metadata: Metadata` - The canonical name of the agent that produced this 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. - - `caller_: Direct{ type} | Program{ caller_id, type}` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The execution context that produced this tool call. + - `model: String` - - `class Direct` + 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. - - `type: :direct` + - `name: String` - - `:direct` + The name of the assistant. The maximum length is 256 characters. - - `class Program` + - `object: :assistant` - - `caller_id: String` + The object type, which is always `assistant`. - The call ID of the program item that produced this tool call. + - `:assistant` - - `type: :program` + - `tools: Array[AssistantTool]` - - `:program` + 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`. - - `created_by: String` + - `class CodeInterpreterTool` - The ID of the entity that created this tool call. + - `type: :code_interpreter` - - `class BetaResponseFunctionShellToolCallOutput` + The type of tool being defined: `code_interpreter` - The output of a shell tool call that was emitted. + - `:code_interpreter` - - `id: String` + - `class FileSearchTool` - The unique ID of the shell call output. Populated when this item is returned via API. + - `type: :file_search` - - `call_id: String` + The type of tool being defined: `file_search` - The unique ID of the shell tool call generated by the model. + - `:file_search` - - `max_output_length: Integer` + - `file_search: FileSearch{ max_num_results, ranking_options}` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Overrides for the file search tool. - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `max_num_results: Integer` - An array of shell call output contents + 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. - - `outcome: Timeout{ type} | Exit{ exit_code, 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. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `class Timeout` + 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 call exceeded its configured time limit. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: :timeout` + - `score_threshold: Float` - The outcome type. Always `timeout`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `:timeout` + - `ranker: :auto | :default_2024_08_21` - - `class Exit` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Indicates that the shell commands finished and returned an exit code. + - `:auto` - - `exit_code: Integer` + - `:default_2024_08_21` - Exit code from the shell process. + - `class FunctionTool` - - `type: :exit` + - `function: FunctionDefinition` - The outcome type. Always `exit`. + - `name: String` - - `:exit` + 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. - - `stderr: String` + - `description: String` - The standard error output that was captured. + A description of what the function does, used by the model to choose when and how to call the function. - - `stdout: String` + - `parameters: FunctionParameters` - The standard output that was captured. + 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. - - `created_by: String` + Omitting `parameters` defines a function with an empty parameter list. - The identifier of the actor that created the item. + - `strict: bool` - - `status: :in_progress | :completed | :incomplete` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `type: :function` - - `:in_progress` + The type of tool being defined: `function` - - `:completed` + - `:function` - - `:incomplete` + - `response_format: AssistantResponseFormatOption` - - `type: :shell_call_output` + 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 type of the shell call output. Always `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](https://platform.openai.com/docs/guides/structured-outputs). - - `:shell_call_output` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `agent: Agent{ agent_name}` + **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 agent that produced this item. + - `AssistantResponseFormatOption = :auto` - - `agent_name: String` + `auto` is the default value - The canonical name of the agent that produced this item. + - `:auto` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class ResponseFormatText` - The execution context that produced this tool call. + Default response format. Used to generate text responses. - - `class Direct` + - `type: :text` - - `type: :direct` + The type of response format being defined. Always `text`. - - `:direct` + - `:text` - - `class Program` + - `class ResponseFormatJSONObject` - - `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`. - - `:program` + - `:json_object` - - `created_by: String` + - `class ResponseFormatJSONSchema` - The identifier of the actor that created the item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `class BetaResponseApplyPatchToolCall` + - `json_schema: JSONSchema{ name, description, schema, strict}` - A tool call that applies file diffs by creating, deleting, or updating files. + Structured Outputs configuration options, including a JSON Schema. - - `id: String` + - `name: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + 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. - - `call_id: String` + - `description: String` - The unique ID of the apply patch tool call generated by the model. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `schema: Hash[Symbol, untyped]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `class CreateFile` + - `strict: bool` - Instruction describing how to create a file via the apply_patch 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](https://platform.openai.com/docs/guides/structured-outputs). - - `diff: String` + - `type: :json_schema` - Diff to apply. + The type of response format being defined. Always `json_schema`. - - `path: String` + - `:json_schema` - Path of the file to create. + - `temperature: Float` - - `type: :create_file` + 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. - Create a new file with the provided diff. + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `:create_file` + 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. - - `class DeleteFile` + - `code_interpreter: CodeInterpreter{ file_ids}` - Instruction describing how to delete a file via the apply_patch tool. + - `file_ids: Array[String]` - - `path: 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. - Path of the file to delete. + - `file_search: FileSearch{ vector_store_ids}` - - `type: :delete_file` + - `vector_store_ids: Array[String]` - Delete the specified file. + 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. - - `:delete_file` + - `top_p: Float` - - `class UpdateFile` + 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. - Instruction describing how to update a file via the apply_patch tool. + We generally recommend altering this or temperature but not both. - - `diff: String` +### Example - Diff to apply. +```ruby +require "openai" - - `path: String` +openai = OpenAI::Client.new(api_key: "My API Key") - Path of the file to update. +page = openai.beta.assistants.list - - `type: :update_file` +puts(page) +``` - Update an existing file with the provided diff. +#### Response - - `:update_file` +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 + } + ], + "first_id": "asst_abc123", + "has_more": false, + "last_id": "asst_abc456", + "object": "list" +} +``` - - `status: :in_progress | :completed` +## Create assistant - The status of the apply patch tool call. One of `in_progress` or `completed`. +`beta.assistants.create(**kwargs) -> Assistant` - - `:in_progress` +**post** `/assistants` - - `:completed` +Create an assistant with a model and instructions. - - `type: :apply_patch_call` +### Parameters - The type of the item. Always `apply_patch_call`. +- `model: String | ChatModel` - - `:apply_patch_call` + 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. - - `agent: Agent{ agent_name}` + - `String = String` - The agent that produced this item. + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` - - `agent_name: String` + - `:"gpt-5.6-sol"` - The canonical name of the agent that produced this item. + - `:"gpt-5.6-terra"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-5.6-luna"` - The execution context that produced this tool call. + - `:"gpt-5.4"` - - `class Direct` + - `:"gpt-5.4-mini"` - - `type: :direct` + - `:"gpt-5.4-nano"` - - `:direct` + - `:"gpt-5.4-mini-2026-03-17"` - - `class Program` + - `:"gpt-5.4-nano-2026-03-17"` - - `caller_id: String` + - `:"gpt-5.3-chat-latest"` - The call ID of the program item that produced this tool call. + - `:"gpt-5.2"` - - `type: :program` + - `:"gpt-5.2-2025-12-11"` - - `:program` + - `:"gpt-5.2-chat-latest"` - - `created_by: String` + - `:"gpt-5.2-pro"` - The ID of the entity that created this tool call. + - `:"gpt-5.2-pro-2025-12-11"` - - `class BetaResponseApplyPatchToolCallOutput` + - `:"gpt-5.1"` - The output emitted by an apply patch tool call. + - `:"gpt-5.1-2025-11-13"` - - `id: String` + - `:"gpt-5.1-codex"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:"gpt-5.1-mini"` - - `call_id: String` + - `:"gpt-5.1-chat-latest"` - The unique ID of the apply patch tool call generated by the model. + - `:"gpt-5"` - - `status: :completed | :failed` + - `:"gpt-5-mini"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `:"gpt-5-nano"` - - `:completed` + - `:"gpt-5-2025-08-07"` - - `:failed` + - `:"gpt-5-mini-2025-08-07"` - - `type: :apply_patch_call_output` + - `:"gpt-5-nano-2025-08-07"` - The type of the item. Always `apply_patch_call_output`. + - `:"gpt-5-chat-latest"` - - `:apply_patch_call_output` + - `:"gpt-4.1"` - - `agent: Agent{ agent_name}` + - `:"gpt-4.1-mini"` - The agent that produced this item. + - `:"gpt-4.1-nano"` - - `agent_name: String` + - `:"gpt-4.1-2025-04-14"` - The canonical name of the agent that produced this item. + - `:"gpt-4.1-mini-2025-04-14"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-4.1-nano-2025-04-14"` - The execution context that produced this tool call. + - `:"o4-mini"` - - `class Direct` + - `:"o4-mini-2025-04-16"` - - `type: :direct` + - `:o3` - - `:direct` + - `:"o3-2025-04-16"` - - `class Program` + - `:"o3-mini"` - - `caller_id: String` + - `:"o3-mini-2025-01-31"` - The call ID of the program item that produced this tool call. + - `:o1` - - `type: :program` + - `:"o1-2024-12-17"` - - `:program` + - `:"o1-preview"` - - `created_by: String` + - `:"o1-preview-2024-09-12"` - The ID of the entity that created this tool call output. + - `:"o1-mini"` - - `output: String` + - `:"o1-mini-2024-09-12"` - Optional textual output returned by the apply patch tool. + - `:"gpt-4o"` - - `class McpCall` + - `:"gpt-4o-2024-11-20"` - An invocation of a tool on an MCP server. + - `:"gpt-4o-2024-08-06"` - - `id: String` + - `:"gpt-4o-2024-05-13"` - The unique ID of the tool call. + - `:"gpt-4o-audio-preview"` - - `arguments: String` + - `:"gpt-4o-audio-preview-2024-10-01"` - A JSON string of the arguments passed to the tool. + - `:"gpt-4o-audio-preview-2024-12-17"` - - `name: String` + - `:"gpt-4o-audio-preview-2025-06-03"` - The name of the tool that was run. + - `:"gpt-4o-mini-audio-preview"` - - `server_label: String` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - The label of the MCP server running the tool. + - `:"gpt-4o-search-preview"` - - `type: :mcp_call` + - `:"gpt-4o-mini-search-preview"` - The type of the item. Always `mcp_call`. + - `:"gpt-4o-search-preview-2025-03-11"` - - `:mcp_call` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - - `agent: Agent{ agent_name}` + - `:"chatgpt-4o-latest"` - The agent that produced this item. + - `:"codex-mini-latest"` - - `agent_name: String` + - `:"gpt-4o-mini"` - The canonical name of the agent that produced this item. + - `:"gpt-4o-mini-2024-07-18"` - - `approval_request_id: String` + - `:"gpt-4-turbo"` - 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. + - `:"gpt-4-turbo-2024-04-09"` - - `error: String` + - `:"gpt-4-0125-preview"` - The error from the tool call, if any. + - `:"gpt-4-turbo-preview"` - - `output: String` + - `:"gpt-4-1106-preview"` - The output from the tool call. + - `:"gpt-4-vision-preview"` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `:"gpt-4"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `:"gpt-4-0314"` - - `:in_progress` + - `:"gpt-4-0613"` - - `:completed` + - `:"gpt-4-32k"` - - `:incomplete` + - `:"gpt-4-32k-0314"` - - `:calling` + - `:"gpt-4-32k-0613"` - - `:failed` + - `:"gpt-3.5-turbo"` - - `class McpListTools` + - `:"gpt-3.5-turbo-16k"` - A list of tools available on an MCP server. + - `:"gpt-3.5-turbo-0301"` - - `id: String` + - `:"gpt-3.5-turbo-0613"` - The unique ID of the list. + - `:"gpt-3.5-turbo-1106"` - - `server_label: String` + - `:"gpt-3.5-turbo-0125"` - The label of the MCP server. + - `:"gpt-3.5-turbo-16k-0613"` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` +- `description: String` - The tools available on the server. + The description of the assistant. The maximum length is 512 characters. - - `input_schema: untyped` +- `instructions: String` - The JSON schema describing the tool's input. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `name: String` +- `metadata: Metadata` - The name of the tool. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `annotations: untyped` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Additional annotations about the tool. +- `name: String` - - `description: String` + The name of the assistant. The maximum length is 256 characters. - The description of the tool. +- `reasoning_effort: ReasoningEffort` - - `type: :mcp_list_tools` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The type of the item. Always `mcp_list_tools`. + - `:none` - - `:mcp_list_tools` + - `:minimal` - - `agent: Agent{ 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` - - `error: String` + - `:max` - Error message if the server could not list tools. +- `response_format: AssistantResponseFormatOption` - - `class McpApprovalRequest` + 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`. - A request for human approval of a tool invocation. + 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: String` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The unique ID of the 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. - - `arguments: String` + - `AssistantResponseFormatOption = :auto` - A JSON string of arguments for the tool. + `auto` is the default value - - `name: String` + - `:auto` - The name of the tool to run. + - `class ResponseFormatText` - - `server_label: String` + Default response format. Used to generate text responses. - The label of the MCP server making the request. + - `type: :text` - - `type: :mcp_approval_request` + The type of response format being defined. Always `text`. - The type of the item. Always `mcp_approval_request`. + - `:text` - - `:mcp_approval_request` + - `class ResponseFormatJSONObject` - - `agent: Agent{ 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` - - `class McpApprovalResponse` + - `class ResponseFormatJSONSchema` - A response to an MCP approval request. + 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: JSONSchema{ name, description, schema, strict}` - The unique ID of the approval response + Structured Outputs configuration options, including a JSON Schema. - - `approval_request_id: String` + - `name: String` - The ID of the approval request being answered. + 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. - - `approve: bool` + - `description: String` - Whether the request was approved. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: :mcp_approval_response` + - `schema: Hash[Symbol, untyped]` - The type of the item. Always `mcp_approval_response`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:mcp_approval_response` + - `strict: bool` - - `agent: Agent{ 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` - - `reason: String` +- `temperature: Float` - Optional reason for the decision. + 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. - - `class BetaResponseCustomToolCall` +- `tool_resources: ToolResources{ code_interpreter, file_search}` - A call to a custom tool created by the model. + 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. - - `class BetaResponseCustomToolCallOutputItem` + - `code_interpreter: CodeInterpreter{ file_ids}` - The output of a custom tool call from your code, being sent back to the model. + - `file_ids: Array[String]` - - `id: 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. - The unique ID of the custom tool call output item. + - `file_search: FileSearch{ vector_store_ids, vector_stores}` - - `status: :in_progress | :completed | :incomplete` + - `vector_store_ids: Array[String]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `:in_progress` + - `vector_stores: Array[VectorStore{ chunking_strategy, file_ids, metadata}]` - - `:completed` + 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. - - `:incomplete` + - `chunking_strategy: Auto{ type} | Static{ static, type}` - - `created_by: String` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - The identifier of the actor that created the item. + - `class Auto` - - `parallel_tool_calls: bool` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - Whether to allow the model to run tool calls in parallel. + - `type: :auto` - - `temperature: Float` + Always `auto`. - 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. + - `:auto` - - `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + - `class Static` - 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. + - `static: Static{ chunk_overlap_tokens, max_chunk_size_tokens}` - - `BetaToolChoiceOptions = :none | :auto | :required` + - `chunk_overlap_tokens: Integer` - Controls which (if any) tool is called by the model. + The number of tokens that overlap between chunks. The default value is `400`. - `none` means the model will not call any tool and instead generates a message. + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `max_chunk_size_tokens: Integer` - `required` means the model must call one or more tools. + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `:none` + - `type: :static` - - `:auto` + Always `static`. - - `:required` + - `:static` - - `class BetaToolChoiceAllowed` + - `file_ids: Array[String]` - Constrains the tools available to the model to a pre-defined set. + 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. - - `mode: :auto | :required` + - `metadata: Metadata` - Constrains the tools available to the model to a pre-defined set. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - `auto` allows the model to pick from among the allowed tools and generate a - message. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - `required` requires the model to call one or more of the allowed tools. +- `tools: Array[AssistantTool]` - - `: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`. - - `:required` + - `class CodeInterpreterTool` - - `tools: Array[Hash[Symbol, untyped]]` + - `type: :code_interpreter` - A list of tool definitions that the model should be allowed to call. + The type of tool being defined: `code_interpreter` - For the Responses API, the list of tool definitions might look like: + - `:code_interpreter` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `class FileSearchTool` - - `type: :allowed_tools` + - `type: :file_search` - Allowed tool configuration type. Always `allowed_tools`. + The type of tool being defined: `file_search` - - `:allowed_tools` + - `:file_search` - - `class BetaToolChoiceTypes` + - `file_search: FileSearch{ max_num_results, ranking_options}` - 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). + Overrides for the file search tool. - - `type: :file_search | :web_search_preview | :computer | 5 more` + - `max_num_results: Integer` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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 values are: + 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. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `:file_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. - - `:web_search_preview` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `:computer` + - `score_threshold: Float` - - `:computer_use_preview` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `:computer_use` + - `ranker: :auto | :default_2024_08_21` - - `:web_search_preview_2025_03_11` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `:image_generation` + - `:auto` - - `:code_interpreter` + - `:default_2024_08_21` - - `class BetaToolChoiceFunction` + - `class FunctionTool` - Use this option to force the model to call a specific function. + - `function: FunctionDefinition` - `name: String` - The name of the function to 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. - - `type: :function` + - `description: String` - For function calling, the type is always `function`. + A description of what the function does, used by the model to choose when and how to call the function. - - `:function` + - `parameters: FunctionParameters` - - `class BetaToolChoiceMcp` + 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. - Use this option to force the model to call a specific tool on a remote MCP server. + Omitting `parameters` defines a function with an empty parameter list. - - `server_label: String` + - `strict: bool` - The label of the MCP server to use. + 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: :mcp` + - `type: :function` - For MCP tools, the type is always `mcp`. + The type of tool being defined: `function` - - `:mcp` + - `:function` - - `name: String` +- `top_p: Float` - The name of the tool to call on the server. + 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. - - `class BetaToolChoiceCustom` + We generally recommend altering this or temperature but not both. - Use this option to force the model to call a specific custom tool. +### Returns - - `name: String` +- `class Assistant` - The name of the custom tool to call. + Represents an `assistant` that can call the model and use tools. - - `type: :custom` + - `id: String` - For custom tool calling, the type is always `custom`. + The identifier, which can be referenced in API endpoints. - - `:custom` + - `created_at: Integer` - - `class BetaSpecificProgrammaticToolCallingParam` + The Unix timestamp (in seconds) for when the assistant was created. - - `type: :programmatic_tool_calling` + - `description: String` - The tool to call. Always `programmatic_tool_calling`. + The description of the assistant. The maximum length is 512 characters. - - `:programmatic_tool_calling` + - `instructions: String` - - `class BetaToolChoiceApplyPatch` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - Forces the model to call the apply_patch tool when executing a tool call. + - `metadata: Metadata` - - `type: :apply_patch` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The tool to call. Always `apply_patch`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `:apply_patch` + - `model: String` - - `class BetaToolChoiceShell` + 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. - Forces the model to call the shell tool when a tool call is required. + - `name: String` - - `type: :shell` + The name of the assistant. The maximum length is 256 characters. - The tool to call. Always `shell`. + - `object: :assistant` - - `:shell` + The object type, which is always `assistant`. - - `tools: Array[BetaTool]` + - `:assistant` - 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[AssistantTool]` - We support the following categories of tools: + 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`. - - **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. + - `class CodeInterpreterTool` - - `class BetaFunctionTool` + - `type: :code_interpreter` - 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 being defined: `code_interpreter` - - `class BetaFileSearchTool` + - `:code_interpreter` - 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). + - `class FileSearchTool` - - `class BetaComputerTool` + - `type: :file_search` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of tool being defined: `file_search` - - `class BetaComputerUsePreviewTool` + - `:file_search` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `class BetaWebSearchTool` + Overrides for the file search tool. - 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_num_results: Integer` - - `class Mcp` + 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](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `class CodeInterpreter` + 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 tool that runs Python code to help generate a response to a prompt. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class ProgrammaticToolCalling` + - `score_threshold: Float` - - `class ImageGeneration` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A tool that generates images using the GPT image models. + - `ranker: :auto | :default_2024_08_21` - - `class LocalShell` + The ranker to use for the file search. If not specified will use the `auto` ranker. - A tool that allows the model to execute shell commands in a local environment. + - `:auto` - - `class BetaFunctionShellTool` + - `:default_2024_08_21` - A tool that allows the model to execute shell commands. + - `class FunctionTool` - - `class BetaCustomTool` + - `function: FunctionDefinition` - 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` - - `class BetaNamespaceTool` + 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: String` - - `class BetaToolSearchTool` + A description of what the function does, used by the model to choose when and how to call the function. - Hosted or BYOT tool search configuration for deferred tools. + - `parameters: FunctionParameters` - - `class BetaWebSearchPreviewTool` + 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. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Omitting `parameters` defines a function with an empty parameter list. - - `class BetaApplyPatchTool` + - `strict: bool` - Allows the assistant to create, delete, or update files using unified diffs. + 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). - - `top_p: Float` + - `type: :function` - 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 tool being defined: `function` - We generally recommend altering this or `temperature` but not both. + - `:function` - - `background: bool` + - `response_format: AssistantResponseFormatOption` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + 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`. - - `completed_at: Float` + 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). - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `conversation: Conversation{ id}` + **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 conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `AssistantResponseFormatOption = :auto` - - `id: String` + `auto` is the default value - The unique ID of the conversation that this response was associated with. + - `:auto` - - `max_output_tokens: Integer` + - `class ResponseFormatText` - 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 response format. Used to generate text responses. - - `max_tool_calls: Integer` + - `type: :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. + The type of response format being defined. Always `text`. - - `moderation: Moderation{ input, output}` + - `:text` - Moderation results for the response input and output, if moderated completions were requested. + - `class ResponseFormatJSONObject` - - `input: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, 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. - Moderation for the response input. + - `type: :json_object` - - `class ModerationResult` + The type of response format being defined. Always `json_object`. - A moderation result produced for the response input or output. + - `:json_object` - - `categories: Hash[Symbol, bool]` + - `class ResponseFormatJSONSchema` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` + - `json_schema: JSONSchema{ name, description, schema, strict}` - Which modalities of input are reflected by the score for each category. + Structured Outputs configuration options, including a JSON Schema. - - `:text` + - `name: String` - - `: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. - - `category_scores: Hash[Symbol, Float]` + - `description: String` - A dictionary of moderation categories to scores. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `flagged: bool` + - `schema: Hash[Symbol, untyped]` - A boolean indicating whether the content was flagged by any category. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `model: String` + - `strict: bool` - The moderation model 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](https://platform.openai.com/docs/guides/structured-outputs). - - `type: :moderation_result` + - `type: :json_schema` - The object type, which was always `moderation_result` for successful moderation results. + The type of response format being defined. Always `json_schema`. - - `:moderation_result` + - `:json_schema` - - `class Error` + - `temperature: Float` - An error produced while attempting moderation for the response input or output. + 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: String` + - `tool_resources: ToolResources{ code_interpreter, file_search}` - The error code. + 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. - - `message: String` + - `code_interpreter: CodeInterpreter{ file_ids}` - The error message. + - `file_ids: Array[String]` - - `type: :error` + 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. - The object type, which was always `error` for moderation failures. + - `file_search: FileSearch{ vector_store_ids}` - - `:error` + - `vector_store_ids: Array[String]` - - `output: ModerationResult{ categories, category_applied_input_types, category_scores, 3 more} | Error{ code, message, type}` + 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. - Moderation for the response output. + - `top_p: Float` - - `class ModerationResult` + 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 moderation result produced for the response input or output. + We generally recommend altering this or temperature but not both. - - `categories: Hash[Symbol, bool]` +### Example - A dictionary of moderation categories to booleans, True if the input is flagged under this category. +```ruby +require "openai" - - `category_applied_input_types: Hash[Symbol, Array[:text | :image]]` +openai = OpenAI::Client.new(api_key: "My API Key") - Which modalities of input are reflected by the score for each category. +assistant = openai.beta.assistants.create(model: :"gpt-4o") - - `:text` +puts(assistant) +``` - - `:image` +#### Response - - `category_scores: Hash[Symbol, Float]` +```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 dictionary of moderation categories to scores. +## Retrieve assistant - - `flagged: bool` +`beta.assistants.retrieve(assistant_id) -> Assistant` - A boolean indicating whether the content was flagged by any category. +**get** `/assistants/{assistant_id}` - - `model: String` +Retrieves an assistant. - The moderation model that produced this result. +### Parameters - - `type: :moderation_result` +- `assistant_id: String` - The object type, which was always `moderation_result` for successful moderation results. +### Returns - - `:moderation_result` +- `class Assistant` - - `class Error` + Represents an `assistant` that can call the model and use tools. - An error produced while attempting moderation for the response input or output. + - `id: String` - - `code: String` + The identifier, which can be referenced in API endpoints. - The error code. + - `created_at: Integer` - - `message: String` + The Unix timestamp (in seconds) for when the assistant was created. - The error message. + - `description: String` - - `type: :error` + The description of the assistant. The maximum length is 512 characters. - The object type, which was always `error` for moderation failures. + - `instructions: String` - - `:error` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `previous_response_id: String` + - `metadata: Metadata` - 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`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `prompt: BetaResponsePrompt` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `model: String` - - `id: String` + 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 unique identifier of the prompt template to use. + - `name: String` - - `variables: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The name of the assistant. The maximum length is 256 characters. - 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. + - `object: :assistant` - - `String = String` + The object type, which is always `assistant`. - - `class BetaResponseInputText` + - `:assistant` - A text input to the model. + - `tools: Array[AssistantTool]` - - `class BetaResponseInputImage` + 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`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class CodeInterpreterTool` - - `class BetaResponseInputFile` + - `type: :code_interpreter` - A file input to the model. + The type of tool being defined: `code_interpreter` - - `version: String` + - `:code_interpreter` - Optional version of the prompt template. + - `class FileSearchTool` - - `prompt_cache_key: String` + - `type: :file_search` - 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 type of tool being defined: `file_search` - - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + - `:file_search` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `mode: :implicit | :explicit` + Overrides for the file search tool. - Whether implicit prompt-cache breakpoints were enabled. + - `max_num_results: Integer` - - `:implicit` + 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. - - `:explicit` + 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. - - `ttl: :"30m"` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - The minimum lifetime applied to each cache breakpoint. + 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. - - `:"30m"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `prompt_cache_retention: :in_memory | :"24h"` + - `score_threshold: Float` - Deprecated. Use `prompt_cache_options.ttl` instead. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - 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. + - `ranker: :auto | :default_2024_08_21` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The ranker to use for the file search. If not specified will use the `auto` ranker. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `:auto` - - `:in_memory` + - `:default_2024_08_21` - - `:"24h"` + - `class FunctionTool` - - `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + - `function: FunctionDefinition` - **gpt-5 and o-series models only** + - `name: String` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + 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. - - `context: :auto | :current_turn | :all_turns` + - `description: 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. + A description of what the function does, used by the model to choose when and how to call the function. - - `:auto` + - `parameters: FunctionParameters` - - `:current_turn` + 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. - - `:all_turns` + Omitting `parameters` defines a function with an empty parameter list. - - `effort: :none | :minimal | :low | 4 more` + - `strict: bool` - 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. + 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). - - `:none` + - `type: :function` - - `:minimal` + The type of tool being defined: `function` - - `:low` + - `:function` - - `:medium` + - `response_format: AssistantResponseFormatOption` - - `:high` + 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`. - - `:xhigh` + 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). - - `:max` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `generate_summary: :auto | :concise | :detailed` + **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. - **Deprecated:** use `summary` instead. + - `AssistantResponseFormatOption = :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` is the default value - `:auto` - - `:concise` - - - `:detailed` + - `class ResponseFormatText` - - `mode: String | :standard | :pro` + Default response format. Used to generate text responses. - Controls the reasoning execution mode for the request. + - `type: :text` - When returned on a response, this is the effective execution mode. + The type of response format being defined. Always `text`. - - `String = String` + - `:text` - - `Mode = :standard | :pro` + - `class ResponseFormatJSONObject` - Controls the reasoning execution mode for the request. + 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. - When returned on a response, this is the effective execution mode. + - `type: :json_object` - - `:standard` + The type of response format being defined. Always `json_object`. - - `:pro` + - `:json_object` - - `summary: :auto | :concise | :detailed` + - `class ResponseFormatJSONSchema` - 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`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `:auto` + Structured Outputs configuration options, including a JSON Schema. - - `:concise` + - `name: String` - - `:detailed` + 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. - - `safety_identifier: String` + - `description: 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). + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `service_tier: :auto | :default | :flex | 2 more` + - `schema: Hash[Symbol, untyped]` - Specifies the processing type used for serving the request. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - 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'. + - `strict: bool` - 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. + 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). - - `:auto` + - `type: :json_schema` - - `:default` + The type of response format being defined. Always `json_schema`. - - `:flex` + - `:json_schema` - - `:scale` + - `temperature: Float` - - `:priority` + 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. - - `status: BetaResponseStatus` + - `tool_resources: ToolResources{ code_interpreter, file_search}` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + 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. - - `:completed` + - `code_interpreter: CodeInterpreter{ file_ids}` - - `:failed` + - `file_ids: Array[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. - - `:cancelled` + - `file_search: FileSearch{ vector_store_ids}` - - `:queued` + - `vector_store_ids: Array[String]` - - `:incomplete` + 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. - - `text: BetaResponseTextConfig` + - `top_p: Float` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn 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. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + We generally recommend altering this or temperature but not both. - - `format_: BetaResponseFormatTextConfig` +### Example - An object specifying the format that the model must output. +```ruby +require "openai" - 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). +openai = OpenAI::Client.new(api_key: "My API Key") - The default format is `{ "type": "text" }` with no additional options. +assistant = openai.beta.assistants.retrieve("assistant_id") - **Not recommended for gpt-4o and newer models:** +puts(assistant) +``` - 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. +#### Response - - `class Text` +```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 +} +``` - Default response format. Used to generate text responses. +## Modify assistant - - `type: :text` +`beta.assistants.update(assistant_id, **kwargs) -> Assistant` - The type of response format being defined. Always `text`. +**post** `/assistants/{assistant_id}` - - `:text` +Modifies an assistant. - - `class BetaResponseFormatTextJSONSchemaConfig` +### Parameters - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). +- `assistant_id: String` - - `name: String` +- `description: 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 description of the assistant. The maximum length is 512 characters. - - `schema: Hash[Symbol, untyped]` +- `instructions: 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 system instructions that the assistant uses. The maximum length is 256,000 characters. - - `type: :json_schema` +- `metadata: Metadata` - The type of response format being defined. Always `json_schema`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `:json_schema` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `description: String` +- `model: String | :"gpt-5" | :"gpt-5-mini" | :"gpt-5-nano" | 39 more` - A description of what the response format is for, used by the model to - determine how to respond in the format. + 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. - - `strict: bool` + - `String = 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). + - `Model = :"gpt-5" | :"gpt-5-mini" | :"gpt-5-nano" | 39 more` - - `class JSONObject` + 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. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `:"gpt-5"` - - `type: :json_object` + - `:"gpt-5-mini"` - The type of response format being defined. Always `json_object`. + - `:"gpt-5-nano"` - - `:json_object` + - `:"gpt-5-2025-08-07"` - - `verbosity: :low | :medium | :high` + - `:"gpt-5-mini-2025-08-07"` - 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`. + - `:"gpt-5-nano-2025-08-07"` - - `:low` + - `:"gpt-4.1"` - - `:medium` + - `:"gpt-4.1-mini"` - - `:high` + - `:"gpt-4.1-nano"` - - `top_logprobs: Integer` + - `:"gpt-4.1-2025-04-14"` - 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. + - `:"gpt-4.1-mini-2025-04-14"` - - `truncation: :auto | :disabled` + - `:"gpt-4.1-nano-2025-04-14"` - The truncation strategy to use for the model response. + - `:"o3-mini"` - - `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. + - `:"o3-mini-2025-01-31"` - - `:auto` + - `:o1` - - `:disabled` + - `:"o1-2024-12-17"` - - `usage: BetaResponseUsage` + - `:"gpt-4o"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `:"gpt-4o-2024-11-20"` - - `input_tokens: Integer` + - `:"gpt-4o-2024-08-06"` - The number of input tokens. + - `:"gpt-4o-2024-05-13"` - - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` + - `:"gpt-4o-mini"` - A detailed breakdown of the input tokens. + - `:"gpt-4o-mini-2024-07-18"` - - `cache_write_tokens: Integer` + - `:"gpt-4.5-preview"` - The number of input tokens that were written to the cache. + - `:"gpt-4.5-preview-2025-02-27"` - - `cached_tokens: Integer` + - `:"gpt-4-turbo"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `:"gpt-4-turbo-2024-04-09"` - - `output_tokens: Integer` + - `:"gpt-4-0125-preview"` - The number of output tokens. + - `:"gpt-4-turbo-preview"` - - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` + - `:"gpt-4-1106-preview"` - A detailed breakdown of the output tokens. + - `:"gpt-4-vision-preview"` - - `reasoning_tokens: Integer` + - `:"gpt-4"` - The number of reasoning tokens. + - `:"gpt-4-0314"` - - `total_tokens: Integer` + - `:"gpt-4-0613"` - The total number of tokens used. + - `:"gpt-4-32k"` - - `user: String` + - `:"gpt-4-32k-0314"` - 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). + - `:"gpt-4-32k-0613"` - - `sequence_number: Integer` + - `:"gpt-3.5-turbo"` - The sequence number for this event. + - `:"gpt-3.5-turbo-16k"` - - `type: :"response.completed"` + - `:"gpt-3.5-turbo-0613"` - The type of the event. Always `response.completed`. + - `:"gpt-3.5-turbo-1106"` - - `:"response.completed"` + - `:"gpt-3.5-turbo-0125"` - - `agent: Agent{ agent_name}` + - `:"gpt-3.5-turbo-16k-0613"` - The agent that owns this multi-agent streaming event. +- `name: String` - - `agent_name: String` + The name of the assistant. The maximum length is 256 characters. - The canonical name of the agent that produced this item. +- `reasoning_effort: ReasoningEffort` - - `class BetaResponseContentPartAddedEvent` + 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. - Emitted when a new content part is added. + - `:none` - - `content_index: Integer` + - `:minimal` - The index of the content part that was added. + - `:low` - - `item_id: String` + - `:medium` - The ID of the output item that the content part was added to. + - `:high` - - `output_index: Integer` + - `:xhigh` - The index of the output item that the content part was added to. + - `:max` - - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` +- `response_format: AssistantResponseFormatOption` - The content part that was added. + 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`. - - `class BetaResponseOutputText` + 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). - A text output from the model. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class BetaResponseOutputRefusal` + **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 refusal from the model. + - `AssistantResponseFormatOption = :auto` - - `class ReasoningText` + `auto` is the default value - Reasoning text from the model. + - `:auto` - - `text: String` + - `class ResponseFormatText` - The reasoning text from the model. + Default response format. Used to generate text responses. - - `type: :reasoning_text` + - `type: :text` - The type of the reasoning text. Always `reasoning_text`. + The type of response format being defined. Always `text`. - - `:reasoning_text` + - `:text` - - `sequence_number: Integer` + - `class ResponseFormatJSONObject` - The sequence number of this event. + 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: :"response.content_part.added"` + - `type: :json_object` - The type of the event. Always `response.content_part.added`. + The type of response format being defined. Always `json_object`. - - `:"response.content_part.added"` + - `:json_object` - - `agent: Agent{ agent_name}` + - `class ResponseFormatJSONSchema` - The agent that owns this multi-agent streaming event. + 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` + - `json_schema: JSONSchema{ name, description, schema, strict}` - The canonical name of the agent that produced this item. + Structured Outputs configuration options, including a JSON Schema. - - `class BetaResponseContentPartDoneEvent` + - `name: String` - Emitted when a content part is done. + 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. - - `content_index: Integer` + - `description: String` - The index of the content part that is done. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `item_id: String` + - `schema: Hash[Symbol, untyped]` - The ID of the output item that the content part was added to. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `output_index: Integer` + - `strict: bool` - The index of the output item that the content part was added to. + 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). - - `part: BetaResponseOutputText | BetaResponseOutputRefusal | ReasoningText{ text, type}` + - `type: :json_schema` - The content part that is done. + The type of response format being defined. Always `json_schema`. - - `class BetaResponseOutputText` + - `:json_schema` - A text output from the model. +- `temperature: Float` - - `class BetaResponseOutputRefusal` + 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 refusal from the model. +- `tool_resources: ToolResources{ code_interpreter, file_search}` - - `class ReasoningText` + 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 from the model. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `text: String` + - `file_ids: Array[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: FileSearch{ vector_store_ids}` - The type of the reasoning text. Always `reasoning_text`. + - `vector_store_ids: Array[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. - - `sequence_number: Integer` +- `tools: Array[AssistantTool]` - The sequence number of this event. + 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`. - - `type: :"response.content_part.done"` + - `class CodeInterpreterTool` - The type of the event. Always `response.content_part.done`. + - `type: :code_interpreter` - - `:"response.content_part.done"` + The type of tool being defined: `code_interpreter` - - `agent: Agent{ agent_name}` + - `:code_interpreter` - The agent that owns this multi-agent streaming event. + - `class FileSearchTool` - - `agent_name: String` + - `type: :file_search` - The canonical name of the agent that produced this item. + The type of tool being defined: `file_search` - - `class BetaResponseCreatedEvent` + - `:file_search` - An event that is emitted when a response is created. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `response: BetaResponse` + Overrides for the file search tool. - The response that was created. + - `max_num_results: Integer` - - `sequence_number: Integer` + 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 sequence number for this event. + 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: :"response.created"` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - The type of the event. Always `response.created`. + 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. - - `:"response.created"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `agent: Agent{ agent_name}` + - `score_threshold: Float` - The agent that owns this multi-agent streaming event. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `agent_name: String` + - `ranker: :auto | :default_2024_08_21` - The canonical name of the agent that produced this item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaResponseErrorEvent` + - `:auto` - Emitted when an error occurs. + - `:default_2024_08_21` - - `code: String` + - `class FunctionTool` - The error code. + - `function: FunctionDefinition` - - `message: String` + - `name: String` - The error message. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `param: String` + - `description: String` - The error parameter. + A description of what the function does, used by the model to choose when and how to call the function. - - `sequence_number: Integer` + - `parameters: FunctionParameters` - The sequence number of this event. + 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: :error` + Omitting `parameters` defines a function with an empty parameter list. - The type of the event. Always `error`. + - `strict: bool` - - `:error` + 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: Agent{ agent_name}` + - `type: :function` - The agent that owns this multi-agent streaming event. + The type of tool being defined: `function` - - `agent_name: String` + - `:function` - The canonical name of the agent that produced this item. +- `top_p: Float` - - `class BetaResponseFileSearchCallCompletedEvent` + 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. - Emitted when a file search call is completed (results found). + We generally recommend altering this or temperature but not both. - - `item_id: String` +### Returns - The ID of the output item that the file search call is initiated. +- `class Assistant` - - `output_index: Integer` + Represents an `assistant` that can call the model and use tools. - The index of the output item that the file search call is initiated. + - `id: String` - - `sequence_number: Integer` + The identifier, which can be referenced in API endpoints. - The sequence number of this event. + - `created_at: Integer` - - `type: :"response.file_search_call.completed"` + The Unix timestamp (in seconds) for when the assistant was created. - The type of the event. Always `response.file_search_call.completed`. + - `description: String` - - `:"response.file_search_call.completed"` + The description of the assistant. The maximum length is 512 characters. - - `agent: Agent{ agent_name}` + - `instructions: String` - The agent that owns this multi-agent streaming event. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `agent_name: String` + - `metadata: Metadata` - The canonical name of the agent that produced this 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. - - `class BetaResponseFileSearchCallInProgressEvent` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Emitted when a file search call is initiated. + - `model: String` - - `item_id: String` + 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 ID of the output item that the file search call is initiated. + - `name: String` - - `output_index: Integer` + The name of the assistant. The maximum length is 256 characters. - The index of the output item that the file search call is initiated. + - `object: :assistant` - - `sequence_number: Integer` + The object type, which is always `assistant`. - The sequence number of this event. + - `:assistant` - - `type: :"response.file_search_call.in_progress"` + - `tools: Array[AssistantTool]` - The type of the event. Always `response.file_search_call.in_progress`. + 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`. - - `:"response.file_search_call.in_progress"` + - `class CodeInterpreterTool` - - `agent: Agent{ agent_name}` + - `type: :code_interpreter` - The agent that owns this multi-agent streaming event. + The type of tool being defined: `code_interpreter` - - `agent_name: String` + - `:code_interpreter` - The canonical name of the agent that produced this item. + - `class FileSearchTool` - - `class BetaResponseFileSearchCallSearchingEvent` + - `type: :file_search` - Emitted when a file search is currently searching. + The type of tool being defined: `file_search` - - `item_id: String` + - `:file_search` - The ID of the output item that the file search call is initiated. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `output_index: Integer` + Overrides for the file search tool. - The index of the output item that the file search call is searching. + - `max_num_results: Integer` - - `sequence_number: Integer` + 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 sequence number of this event. + 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: :"response.file_search_call.searching"` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - The type of the event. Always `response.file_search_call.searching`. + 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. - - `:"response.file_search_call.searching"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `agent: Agent{ agent_name}` + - `score_threshold: Float` - The agent that owns this multi-agent streaming event. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `agent_name: String` + - `ranker: :auto | :default_2024_08_21` - The canonical name of the agent that produced this item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaResponseFunctionCallArgumentsDeltaEvent` + - `:auto` - Emitted when there is a partial function-call arguments delta. + - `:default_2024_08_21` - - `delta: String` + - `class FunctionTool` - The function-call arguments delta that is added. + - `function: FunctionDefinition` - - `item_id: String` + - `name: String` - The ID of the output item that the function-call arguments delta is added to. + 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_index: Integer` + - `description: String` - The index of the output item that the function-call arguments delta is added to. + A description of what the function does, used by the model to choose when and how to call the function. - - `sequence_number: Integer` + - `parameters: FunctionParameters` - The sequence number of this event. + 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: :"response.function_call_arguments.delta"` + Omitting `parameters` defines a function with an empty parameter list. - The type of the event. Always `response.function_call_arguments.delta`. + - `strict: bool` - - `:"response.function_call_arguments.delta"` + 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: Agent{ agent_name}` + - `type: :function` - The agent that owns this multi-agent streaming event. + The type of tool being defined: `function` - - `agent_name: String` + - `:function` - The canonical name of the agent that produced this item. + - `response_format: AssistantResponseFormatOption` - - `class BetaResponseFunctionCallArgumentsDoneEvent` + 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`. - Emitted when function-call arguments are finalized. + 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). - - `arguments: String` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The function-call arguments. + **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. - - `item_id: String` + - `AssistantResponseFormatOption = :auto` - The ID of the item. + `auto` is the default value - - `name: String` + - `:auto` - The name of the function that was called. + - `class ResponseFormatText` - - `output_index: Integer` + Default response format. Used to generate text responses. - The index of the output item. + - `type: :text` - - `sequence_number: Integer` + The type of response format being defined. Always `text`. - The sequence number of this event. + - `:text` - - `type: :"response.function_call_arguments.done"` + - `class ResponseFormatJSONObject` - - `:"response.function_call_arguments.done"` + 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: Agent{ agent_name}` + - `type: :json_object` - The agent that owns this multi-agent streaming event. + The type of response format being defined. Always `json_object`. - - `agent_name: String` + - `:json_object` - The canonical name of the agent that produced this item. + - `class ResponseFormatJSONSchema` - - `class BetaResponseInProgressEvent` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Emitted when the response is in progress. + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `response: BetaResponse` + Structured Outputs configuration options, including a JSON Schema. - The response that is in progress. + - `name: String` - - `sequence_number: Integer` + 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 sequence number of this event. + - `description: String` - - `type: :"response.in_progress"` + 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 event. Always `response.in_progress`. + - `schema: Hash[Symbol, untyped]` - - `:"response.in_progress"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `agent: Agent{ agent_name}` + - `strict: bool` - The agent that owns this multi-agent streaming event. + 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_name: String` + - `type: :json_schema` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `json_schema`. - - `class BetaResponseFailedEvent` + - `:json_schema` - An event that is emitted when a response fails. + - `temperature: Float` - - `response: BetaResponse` + 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 response that failed. + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `sequence_number: Integer` + 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 sequence number of this event. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `type: :"response.failed"` + - `file_ids: Array[String]` - The type of the event. Always `response.failed`. + 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. - - `:"response.failed"` + - `file_search: FileSearch{ vector_store_ids}` - - `agent: Agent{ agent_name}` + - `vector_store_ids: Array[String]` - The agent that owns this multi-agent streaming event. + 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. - - `agent_name: String` + - `top_p: Float` - The canonical name of the agent that produced this item. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `class BetaResponseIncompleteEvent` + We generally recommend altering this or temperature but not both. - An event that is emitted when a response finishes as incomplete. +### Example - - `response: BetaResponse` +```ruby +require "openai" - The response that was incomplete. +openai = OpenAI::Client.new(api_key: "My API Key") - - `sequence_number: Integer` +assistant = openai.beta.assistants.update("assistant_id") - The sequence number of this event. +puts(assistant) +``` - - `type: :"response.incomplete"` +#### Response - The type of the event. Always `response.incomplete`. +```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 +} +``` - - `:"response.incomplete"` +## Delete assistant - - `agent: Agent{ agent_name}` +`beta.assistants.delete(assistant_id) -> AssistantDeleted` - The agent that owns this multi-agent streaming event. +**delete** `/assistants/{assistant_id}` - - `agent_name: String` +Delete an assistant. - The canonical name of the agent that produced this item. +### Parameters - - `class BetaResponseOutputItemAddedEvent` +- `assistant_id: String` - Emitted when a new output item is added. +### Returns - - `item: BetaResponseOutputItem` +- `class AssistantDeleted` - The output item that was added. + - `id: String` - - `class BetaResponseOutputMessage` + - `deleted: bool` - An output message from the model. + - `object: :"assistant.deleted"` - - `class BetaResponseFileSearchToolCall` + - `:"assistant.deleted"` - 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. +### Example - - `class BetaResponseFunctionToolCall` +```ruby +require "openai" - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +openai = OpenAI::Client.new(api_key: "My API Key") - - `class BetaResponseFunctionToolCallOutputItem` +assistant_deleted = openai.beta.assistants.delete("assistant_id") - - `class AgentMessage` +puts(assistant_deleted) +``` - - `class MultiAgentCall` +#### Response - - `class MultiAgentCallOutput` +```json +{ + "id": "id", + "deleted": true, + "object": "assistant.deleted" +} +``` - - `class BetaResponseFunctionWebSearch` +## Domain Types - 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. +### Assistant - - `class BetaResponseComputerToolCall` +- `class Assistant` - 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. + Represents an `assistant` that can call the model and use tools. - - `class BetaResponseComputerToolCallOutputItem` + - `id: String` - - `class BetaResponseReasoningItem` + The identifier, which can be referenced in API endpoints. - 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). + - `created_at: Integer` - - `class Program` + The Unix timestamp (in seconds) for when the assistant was created. - - `class ProgramOutput` + - `description: String` - - `class BetaResponseToolSearchCall` + The description of the assistant. The maximum length is 512 characters. - - `class BetaResponseToolSearchOutputItem` + - `instructions: String` - - `class AdditionalTools` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `class BetaResponseCompactionItem` + - `metadata: Metadata` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class ImageGenerationCall` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - An image generation request made by the model. + - `model: String` - - `class BetaResponseCodeInterpreterToolCall` + 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 tool call to run code. + - `name: String` - - `class LocalShellCall` + The name of the assistant. The maximum length is 256 characters. - A tool call to run a command on the local shell. + - `object: :assistant` - - `class LocalShellCallOutput` + The object type, which is always `assistant`. - The output of a local shell tool call. + - `:assistant` - - `class BetaResponseFunctionShellToolCall` + - `tools: Array[AssistantTool]` - A tool call that executes one or more shell commands in a managed environment. + 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`. - - `class BetaResponseFunctionShellToolCallOutput` + - `class CodeInterpreterTool` - The output of a shell tool call that was emitted. + - `type: :code_interpreter` - - `class BetaResponseApplyPatchToolCall` + The type of tool being defined: `code_interpreter` - A tool call that applies file diffs by creating, deleting, or updating files. + - `:code_interpreter` - - `class BetaResponseApplyPatchToolCallOutput` + - `class FileSearchTool` - The output emitted by an apply patch tool call. + - `type: :file_search` - - `class McpCall` + The type of tool being defined: `file_search` - An invocation of a tool on an MCP server. + - `:file_search` - - `class McpListTools` + - `file_search: FileSearch{ max_num_results, ranking_options}` - A list of tools available on an MCP server. + Overrides for the file search tool. - - `class McpApprovalRequest` + - `max_num_results: Integer` - A request for human approval of a tool invocation. + 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. - - `class McpApprovalResponse` + 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 response to an MCP approval request. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `class BetaResponseCustomToolCall` + 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 call to a custom tool created by the model. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaResponseCustomToolCallOutputItem` + - `score_threshold: Float` - The output of a custom tool call from your code, being sent back to the model. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `output_index: Integer` + - `ranker: :auto | :default_2024_08_21` - The index of the output item that was added. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `sequence_number: Integer` + - `:auto` - The sequence number of this event. + - `:default_2024_08_21` - - `type: :"response.output_item.added"` + - `class FunctionTool` - The type of the event. Always `response.output_item.added`. + - `function: FunctionDefinition` - - `:"response.output_item.added"` + - `name: String` - - `agent: Agent{ agent_name}` + 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 agent that owns this multi-agent streaming event. + - `description: String` - - `agent_name: String` + A description of what the function does, used by the model to choose when and how to call the function. - The canonical name of the agent that produced this item. + - `parameters: FunctionParameters` - - `class BetaResponseOutputItemDoneEvent` + 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. - Emitted when an output item is marked done. + Omitting `parameters` defines a function with an empty parameter list. - - `item: BetaResponseOutputItem` + - `strict: bool` - The output item that was marked done. + 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). - - `output_index: Integer` + - `type: :function` - The index of the output item that was marked done. + The type of tool being defined: `function` - - `sequence_number: Integer` + - `:function` - The sequence number of this event. + - `response_format: AssistantResponseFormatOption` - - `type: :"response.output_item.done"` + 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 type of the event. Always `response.output_item.done`. + 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). - - `:"response.output_item.done"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `agent: Agent{ agent_name}` + **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 agent that owns this multi-agent streaming event. + - `AssistantResponseFormatOption = :auto` - - `agent_name: String` + `auto` is the default value - The canonical name of the agent that produced this item. + - `:auto` - - `class BetaResponseReasoningSummaryPartAddedEvent` + - `class ResponseFormatText` - Emitted when a new reasoning summary part is added. + Default response format. Used to generate text responses. - - `item_id: String` + - `type: :text` - The ID of the item this summary part is associated with. + The type of response format being defined. Always `text`. - - `output_index: Integer` + - `:text` - The index of the output item this summary part is associated with. + - `class ResponseFormatJSONObject` - - `part: Part{ text, 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 summary part that was added. + - `type: :json_object` - - `text: String` + The type of response format being defined. Always `json_object`. - The text of the summary part. + - `:json_object` - - `type: :summary_text` + - `class ResponseFormatJSONSchema` - The type of the summary part. Always `summary_text`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:summary_text` + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `sequence_number: Integer` + Structured Outputs configuration options, including a JSON Schema. - The sequence number of this event. + - `name: String` - - `summary_index: Integer` + 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 summary part within the reasoning summary. + - `description: String` - - `type: :"response.reasoning_summary_part.added"` + 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 event. Always `response.reasoning_summary_part.added`. + - `schema: Hash[Symbol, untyped]` - - `:"response.reasoning_summary_part.added"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `agent: Agent{ agent_name}` + - `strict: bool` - The agent that owns this multi-agent streaming event. + 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_name: String` + - `type: :json_schema` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `json_schema`. - - `class BetaResponseReasoningSummaryPartDoneEvent` + - `:json_schema` - Emitted when a reasoning summary part is completed. + - `temperature: Float` - - `item_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. - The ID of the item this summary part is associated with. + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `output_index: Integer` + 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 index of the output item this summary part is associated with. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `part: Part{ text, type}` + - `file_ids: Array[String]` - The completed summary part. + 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. - - `text: String` + - `file_search: FileSearch{ vector_store_ids}` - The text of the summary part. + - `vector_store_ids: Array[String]` - - `type: :summary_text` + 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 type of the summary part. Always `summary_text`. + - `top_p: Float` - - `:summary_text` + 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. - - `sequence_number: Integer` + We generally recommend altering this or temperature but not both. - The sequence number of this event. +### Assistant Deleted - - `summary_index: Integer` +- `class AssistantDeleted` - The index of the summary part within the reasoning summary. + - `id: String` - - `type: :"response.reasoning_summary_part.done"` + - `deleted: bool` - The type of the event. Always `response.reasoning_summary_part.done`. + - `object: :"assistant.deleted"` - - `:"response.reasoning_summary_part.done"` + - `:"assistant.deleted"` - - `agent: Agent{ agent_name}` +### Assistant Stream Event - The agent that owns this multi-agent streaming event. +- `AssistantStreamEvent = ThreadCreated{ data, event, enabled} | ThreadRunCreated{ data, event} | ThreadRunQueued{ data, event} | 21 more` - - `agent_name: String` + Represents an event emitted when streaming a Run. - The canonical name of the agent that produced this item. + Each event in a server-sent events stream has an `event` and `data` property: - - `status: :incomplete` + ``` + event: thread.created + data: {"id": "thread_123", "object": "thread", ...} + ``` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + 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. - - `:incomplete` + 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. - - `class BetaResponseReasoningSummaryTextDeltaEvent` + - `class ThreadCreated` - Emitted when a delta is added to a reasoning summary text. + Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - `delta: String` + - `data: Thread` - The text delta that was added to the summary. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `item_id: String` + - `id: String` - The ID of the item this summary text delta is associated with. + The identifier, which can be referenced in API endpoints. - - `output_index: Integer` + - `created_at: Integer` - The index of the output item this summary text delta is associated with. + The Unix timestamp (in seconds) for when the thread was created. - - `sequence_number: Integer` + - `metadata: Metadata` - The sequence number of this event. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `summary_index: Integer` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The index of the summary part within the reasoning summary. + - `object: :thread` - - `type: :"response.reasoning_summary_text.delta"` + The object type, which is always `thread`. - The type of the event. Always `response.reasoning_summary_text.delta`. + - `:thread` - - `:"response.reasoning_summary_text.delta"` + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `agent: Agent{ agent_name}` + 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 agent that owns this multi-agent streaming event. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `agent_name: String` + - `file_ids: Array[String]` - The canonical name of the agent that produced this item. + 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. - - `class BetaResponseReasoningSummaryTextDoneEvent` + - `file_search: FileSearch{ vector_store_ids}` - Emitted when a reasoning summary text is completed. + - `vector_store_ids: Array[String]` - - `item_id: 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 item this summary text is associated with. + - `event: :"thread.created"` - - `output_index: Integer` + - `:"thread.created"` - The index of the output item this summary text is associated with. + - `enabled: bool` - - `sequence_number: Integer` + Whether to enable input audio transcription. - The sequence number of this event. + - `class ThreadRunCreated` - - `summary_index: Integer` + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - The index of the summary part within the reasoning summary. + - `data: Run` - - `text: String` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The full text of the completed reasoning summary. + - `id: String` - - `type: :"response.reasoning_summary_text.done"` + The identifier, which can be referenced in API endpoints. - The type of the event. Always `response.reasoning_summary_text.done`. + - `assistant_id: String` - - `:"response.reasoning_summary_text.done"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `agent: Agent{ agent_name}` + - `cancelled_at: Integer` - The agent that owns this multi-agent streaming event. + The Unix timestamp (in seconds) for when the run was cancelled. - - `agent_name: String` + - `completed_at: Integer` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was completed. - - `class BetaResponseReasoningTextDeltaEvent` + - `created_at: Integer` - Emitted when a delta is added to a reasoning text. + The Unix timestamp (in seconds) for when the run was created. - - `content_index: Integer` + - `expires_at: Integer` - The index of the reasoning content part this delta is associated with. + The Unix timestamp (in seconds) for when the run will expire. - - `delta: String` + - `failed_at: Integer` - The text delta that was added to the reasoning content. + The Unix timestamp (in seconds) for when the run failed. - - `item_id: String` + - `incomplete_details: IncompleteDetails{ reason}` - The ID of the item this reasoning text delta is associated with. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `output_index: Integer` + - `reason: :max_completion_tokens | :max_prompt_tokens` - The index of the output item this reasoning text delta is associated with. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `sequence_number: Integer` + - `:max_completion_tokens` - The sequence number of this event. + - `:max_prompt_tokens` - - `type: :"response.reasoning_text.delta"` + - `instructions: String` - The type of the event. Always `response.reasoning_text.delta`. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `:"response.reasoning_text.delta"` + - `last_error: LastError{ code, message}` - - `agent: Agent{ agent_name}` + The last error associated with this run. Will be `null` if there are no errors. - The agent that owns this multi-agent streaming event. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - - `agent_name: String` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The canonical name of the agent that produced this item. + - `:server_error` - - `class BetaResponseReasoningTextDoneEvent` + - `:rate_limit_exceeded` - Emitted when a reasoning text is completed. + - `:invalid_prompt` - - `content_index: Integer` + - `message: String` - The index of the reasoning content part. + A human-readable description of the error. - - `item_id: String` + - `max_completion_tokens: Integer` - The ID of the item this reasoning text is associated with. + The maximum number of completion tokens specified to have been used over the course of the run. - - `output_index: Integer` + - `max_prompt_tokens: Integer` - The index of the output item this reasoning text is associated with. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `sequence_number: Integer` + - `metadata: Metadata` - The sequence number of this event. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `text: String` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The full text of the completed reasoning content. + - `model: String` - - `type: :"response.reasoning_text.done"` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the event. Always `response.reasoning_text.done`. + - `object: :"thread.run"` - - `:"response.reasoning_text.done"` + The object type, which is always `thread.run`. - - `agent: Agent{ agent_name}` + - `:"thread.run"` - The agent that owns this multi-agent streaming event. + - `parallel_tool_calls: bool` - - `agent_name: String` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The canonical name of the agent that produced this item. + - `required_action: RequiredAction{ submit_tool_outputs, type}` - - `class BetaResponseRefusalDeltaEvent` + Details on the action required to continue the run. Will be `null` if no action is required. - Emitted when there is a partial refusal text. + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - - `content_index: Integer` + Details on the tool outputs needed for this run to continue. - The index of the content part that the refusal text is added to. + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `delta: String` + A list of the relevant tool calls. - The refusal text that is added. + - `id: String` - - `item_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 ID of the output item that the refusal text is added to. + - `function: Function{ arguments, name}` - - `output_index: Integer` + The function definition. - The index of the output item that the refusal text is added to. + - `arguments: String` - - `sequence_number: Integer` + The arguments that the model expects you to pass to the function. - The sequence number of this event. + - `name: String` - - `type: :"response.refusal.delta"` + The name of the function. - The type of the event. Always `response.refusal.delta`. + - `type: :function` - - `:"response.refusal.delta"` + The type of tool call the output is required for. For now, this is always `function`. - - `agent: Agent{ agent_name}` + - `:function` - The agent that owns this multi-agent streaming event. + - `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` - - `class BetaResponseRefusalDoneEvent` + - `response_format: AssistantResponseFormatOption` - Emitted when refusal text is finalized. + 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`. - - `content_index: Integer` + 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 index of the content part that the refusal text is finalized. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `item_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 ID of the output item that the refusal text is finalized. + - `AssistantResponseFormatOption = :auto` - - `output_index: Integer` + `auto` is the default value - The index of the output item that the refusal text is finalized. + - `:auto` - - `refusal: String` + - `class ResponseFormatText` - The refusal text that is finalized. + Default response format. Used to generate text responses. - - `sequence_number: Integer` + - `type: :text` - The sequence number of this event. + The type of response format being defined. Always `text`. - - `type: :"response.refusal.done"` + - `:text` - The type of the event. Always `response.refusal.done`. + - `class ResponseFormatJSONObject` - - `:"response.refusal.done"` + 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: Agent{ agent_name}` + - `type: :json_object` - The agent that owns this multi-agent streaming event. + The type of response format being defined. Always `json_object`. - - `agent_name: String` + - `:json_object` - The canonical name of the agent that produced this item. + - `class ResponseFormatJSONSchema` - - `class BetaResponseTextDeltaEvent` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Emitted when there is an additional text delta. + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `content_index: Integer` + Structured Outputs configuration options, including a JSON Schema. - The index of the content part that the text delta was added to. + - `name: String` - - `delta: 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 text delta that was added. + - `description: String` - - `item_id: String` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The ID of the output item that the text delta was added to. + - `schema: Hash[Symbol, untyped]` - - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The log probabilities of the tokens in the delta. + - `strict: bool` - - `token: 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). - A possible text token. + - `type: :json_schema` - - `logprob: Float` + The type of response format being defined. Always `json_schema`. - The log probability of this token. + - `:json_schema` - - `top_logprobs: Array[TopLogprob{ token, logprob}]` + - `started_at: Integer` - The log probabilities of up to 20 of the most likely tokens. + The Unix timestamp (in seconds) for when the run was started. - - `token: String` + - `status: RunStatus` - A possible text token. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `logprob: Float` + - `:queued` - The log probability of this token. + - `:in_progress` - - `output_index: Integer` + - `:requires_action` - The index of the output item that the text delta was added to. + - `:cancelling` - - `sequence_number: Integer` + - `:cancelled` - The sequence number for this event. + - `:failed` - - `type: :"response.output_text.delta"` + - `:completed` - The type of the event. Always `response.output_text.delta`. + - `:incomplete` - - `:"response.output_text.delta"` + - `:expired` - - `agent: Agent{ agent_name}` + - `thread_id: String` - The agent that owns this multi-agent streaming event. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `agent_name: String` + - `tool_choice: AssistantToolChoiceOption` - The canonical name of 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. - - `class BetaResponseTextDoneEvent` + - `Auto = :none | :auto | :required` - Emitted when text content is finalized. + `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_index: Integer` + - `:none` - The index of the content part that the text content is finalized. + - `:auto` - - `item_id: String` + - `:required` - The ID of the output item that the text content is finalized. + - `class AssistantToolChoice` - - `logprobs: Array[Logprob{ token, logprob, top_logprobs}]` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The log probabilities of the tokens in the delta. + - `type: :function | :code_interpreter | :file_search` - - `token: String` + The type of the tool. If type is `function`, the function name must be set - A possible text token. + - `:function` - - `logprob: Float` + - `:code_interpreter` - The log probability of this token. + - `:file_search` - - `top_logprobs: Array[TopLogprob{ token, logprob}]` + - `function: AssistantToolChoiceFunction` - The log probabilities of up to 20 of the most likely tokens. + - `name: String` - - `token: String` + The name of the function to call. - A possible text token. + - `tools: Array[AssistantTool]` - - `logprob: Float` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The log probability of this token. + - `class CodeInterpreterTool` - - `output_index: Integer` + - `type: :code_interpreter` - The index of the output item that the text content is finalized. + The type of tool being defined: `code_interpreter` - - `sequence_number: Integer` + - `:code_interpreter` - The sequence number for this event. + - `class FileSearchTool` - - `text: String` + - `type: :file_search` - The text content that is finalized. + The type of tool being defined: `file_search` - - `type: :"response.output_text.done"` + - `:file_search` - The type of the event. Always `response.output_text.done`. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `:"response.output_text.done"` + Overrides for the file search tool. - - `agent: Agent{ agent_name}` + - `max_num_results: Integer` - The agent that owns this multi-agent streaming event. + 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. - - `agent_name: 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 canonical name of the agent that produced this item. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `class BetaResponseWebSearchCallCompletedEvent` + 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. - Emitted when a web search call is completed. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `item_id: String` + - `score_threshold: Float` - Unique ID for the output item associated with the web search call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `output_index: Integer` + - `ranker: :auto | :default_2024_08_21` - The index of the output item that the web search call is associated with. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `sequence_number: Integer` + - `:auto` - The sequence number of the web search call being processed. + - `:default_2024_08_21` - - `type: :"response.web_search_call.completed"` + - `class FunctionTool` - The type of the event. Always `response.web_search_call.completed`. + - `function: FunctionDefinition` - - `:"response.web_search_call.completed"` + - `name: String` - - `agent: Agent{ agent_name}` + 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 agent that owns this multi-agent streaming event. + - `description: String` - - `agent_name: String` + A description of what the function does, used by the model to choose when and how to call the function. - The canonical name of the agent that produced this item. + - `parameters: FunctionParameters` - - `class BetaResponseWebSearchCallInProgressEvent` + 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. - Emitted when a web search call is initiated. + Omitting `parameters` defines a function with an empty parameter list. - - `item_id: String` + - `strict: bool` - Unique ID for the output item associated with the web search 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). - - `output_index: Integer` + - `type: :function` - The index of the output item that the web search call is associated with. + The type of tool being defined: `function` - - `sequence_number: Integer` + - `:function` - The sequence number of the web search call being processed. + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - - `type: :"response.web_search_call.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. - The type of the event. Always `response.web_search_call.in_progress`. + - `type: :auto | :last_messages` - - `:"response.web_search_call.in_progress"` + 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`. - - `agent: Agent{ agent_name}` + - `:auto` - The agent that owns this multi-agent streaming event. + - `:last_messages` - - `agent_name: String` + - `last_messages: Integer` - The canonical name of the agent that produced this item. + The number of most recent messages from the thread when constructing the context for the run. - - `class BetaResponseWebSearchCallSearchingEvent` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - Emitted when a web search call is executing. + 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.). - - `item_id: String` + - `completion_tokens: Integer` - Unique ID for the output item associated with the web search call. + Number of completion tokens used over the course of the run. - - `output_index: Integer` + - `prompt_tokens: Integer` - The index of the output item that the web search call is associated with. + Number of prompt tokens used over the course of the run. - - `sequence_number: Integer` + - `total_tokens: Integer` - The sequence number of the web search call being processed. + Total number of tokens used (prompt + completion). - - `type: :"response.web_search_call.searching"` + - `temperature: Float` - The type of the event. Always `response.web_search_call.searching`. + The sampling temperature used for this run. If not set, defaults to 1. - - `:"response.web_search_call.searching"` + - `top_p: Float` - - `agent: Agent{ agent_name}` + The nucleus sampling value used for this run. If not set, defaults to 1. - The agent that owns this multi-agent streaming event. + - `event: :"thread.run.created"` - - `agent_name: String` + - `:"thread.run.created"` - The canonical name of the agent that produced this item. + - `class ThreadRunQueued` - - `class BetaResponseImageGenCallCompletedEvent` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - Emitted when an image generation tool call has completed and the final image is available. + - `data: Run` - - `item_id: String` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The unique identifier of the image generation item being processed. + - `event: :"thread.run.queued"` - - `output_index: Integer` + - `:"thread.run.queued"` - The index of the output item in the response's output array. + - `class ThreadRunInProgress` - - `sequence_number: Integer` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - The sequence number of this event. + - `data: Run` - - `type: :"response.image_generation_call.completed"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the event. Always 'response.image_generation_call.completed'. + - `event: :"thread.run.in_progress"` - - `:"response.image_generation_call.completed"` + - `:"thread.run.in_progress"` - - `agent: Agent{ agent_name}` + - `class ThreadRunRequiresAction` - The agent that owns this multi-agent streaming event. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - `agent_name: String` + - `data: Run` - 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). - - `class BetaResponseImageGenCallGeneratingEvent` + - `event: :"thread.run.requires_action"` - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `:"thread.run.requires_action"` - - `item_id: String` + - `class ThreadRunCompleted` - The unique identifier of the image generation item being processed. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - - `output_index: Integer` + - `data: Run` - The index of the output item in the response's output array. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `sequence_number: Integer` + - `event: :"thread.run.completed"` - The sequence number of the image generation item being processed. + - `:"thread.run.completed"` - - `type: :"response.image_generation_call.generating"` + - `class ThreadRunIncomplete` - The type of the event. Always 'response.image_generation_call.generating'. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - - `:"response.image_generation_call.generating"` + - `data: Run` - - `agent: Agent{ agent_name}` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The agent that owns this multi-agent streaming event. + - `event: :"thread.run.incomplete"` - - `agent_name: String` + - `:"thread.run.incomplete"` - The canonical name of the agent that produced this item. + - `class ThreadRunFailed` - - `class BetaResponseImageGenCallInProgressEvent` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - Emitted when an image generation tool call is in progress. + - `data: Run` - - `item_id: String` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The unique identifier of the image generation item being processed. + - `event: :"thread.run.failed"` - - `output_index: Integer` + - `:"thread.run.failed"` - The index of the output item in the response's output array. + - `class ThreadRunCancelling` - - `sequence_number: Integer` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - The sequence number of the image generation item being processed. + - `data: Run` - - `type: :"response.image_generation_call.in_progress"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the event. Always 'response.image_generation_call.in_progress'. + - `event: :"thread.run.cancelling"` - - `:"response.image_generation_call.in_progress"` + - `:"thread.run.cancelling"` - - `agent: Agent{ agent_name}` + - `class ThreadRunCancelled` - The agent that owns this multi-agent streaming event. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - - `agent_name: String` + - `data: Run` - 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). - - `class BetaResponseImageGenCallPartialImageEvent` + - `event: :"thread.run.cancelled"` - Emitted when a partial image is available during image generation streaming. + - `:"thread.run.cancelled"` - - `item_id: String` + - `class ThreadRunExpired` - The unique identifier of the image generation item being processed. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - - `output_index: Integer` + - `data: Run` - The index of the output item in the response's output array. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `partial_image_b64: String` + - `event: :"thread.run.expired"` - Base64-encoded partial image data, suitable for rendering as an image. + - `:"thread.run.expired"` - - `partial_image_index: Integer` + - `class ThreadRunStepCreated` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `sequence_number: Integer` + - `data: RunStep` - The sequence number of the image generation item being processed. + Represents a step in execution of a run. - - `type: :"response.image_generation_call.partial_image"` + - `id: String` - The type of the event. Always 'response.image_generation_call.partial_image'. + The identifier of the run step, which can be referenced in API endpoints. - - `:"response.image_generation_call.partial_image"` + - `assistant_id: String` - - `agent: Agent{ agent_name}` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The agent that owns this multi-agent streaming event. + - `cancelled_at: Integer` - - `agent_name: String` + The Unix timestamp (in seconds) for when the run step was cancelled. - The canonical name of the agent that produced this item. + - `completed_at: Integer` - - `class BetaResponseMcpCallArgumentsDeltaEvent` + The Unix timestamp (in seconds) for when the run step completed. - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `created_at: Integer` - - `delta: String` + The Unix timestamp (in seconds) for when the run step was created. - A JSON string containing the partial update to the arguments for the MCP tool call. + - `expired_at: Integer` - - `item_id: String` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The unique identifier of the MCP tool call item being processed. + - `failed_at: Integer` - - `output_index: Integer` + The Unix timestamp (in seconds) for when the run step failed. - The index of the output item in the response's output array. + - `last_error: LastError{ code, message}` - - `sequence_number: Integer` + The last error associated with this run step. Will be `null` if there are no errors. - The sequence number of this event. + - `code: :server_error | :rate_limit_exceeded` - - `type: :"response.mcp_call_arguments.delta"` + One of `server_error` or `rate_limit_exceeded`. - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `:server_error` - - `:"response.mcp_call_arguments.delta"` + - `:rate_limit_exceeded` - - `agent: Agent{ agent_name}` + - `message: String` - The agent that owns this multi-agent streaming event. + A human-readable description of the error. - - `agent_name: String` + - `metadata: Metadata` - The canonical name of the agent that produced this 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. - - `class BetaResponseMcpCallArgumentsDoneEvent` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Emitted when the arguments for an MCP tool call are finalized. + - `object: :"thread.run.step"` - - `arguments: String` + The object type, which is always `thread.run.step`. - A JSON string containing the finalized arguments for the MCP tool call. + - `:"thread.run.step"` - - `item_id: String` + - `run_id: String` - The unique identifier of the MCP tool call item being processed. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `output_index: Integer` + - `status: :in_progress | :cancelled | :failed | 2 more` - The index of the output item in the response's output array. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `sequence_number: Integer` + - `:in_progress` - The sequence number of this event. + - `:cancelled` - - `type: :"response.mcp_call_arguments.done"` + - `:failed` - The type of the event. Always 'response.mcp_call_arguments.done'. + - `:completed` - - `:"response.mcp_call_arguments.done"` + - `:expired` - - `agent: Agent{ agent_name}` + - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` - The agent that owns this multi-agent streaming event. + The details of the run step. - - `agent_name: String` + - `class MessageCreationStepDetails` - The canonical name of the agent that produced this item. + Details of the message creation by the run step. - - `class BetaResponseMcpCallCompletedEvent` + - `message_creation: MessageCreation{ message_id}` - Emitted when an MCP tool call has completed successfully. + - `message_id: String` - - `item_id: String` + The ID of the message that was created by this run step. - The ID of the MCP tool call item that completed. + - `type: :message_creation` - - `output_index: Integer` + Always `message_creation`. - The index of the output item that completed. + - `:message_creation` - - `sequence_number: Integer` + - `class ToolCallsStepDetails` - The sequence number of this event. + Details of the tool call. - - `type: :"response.mcp_call.completed"` + - `tool_calls: Array[ToolCall]` - The type of the event. Always 'response.mcp_call.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`. - - `:"response.mcp_call.completed"` + - `class CodeInterpreterToolCall` - - `agent: Agent{ agent_name}` + Details of the Code Interpreter tool call the run step was involved in. - The agent that owns this multi-agent streaming event. + - `id: String` - - `agent_name: String` + The ID of the tool call. - The canonical name of the agent that produced this item. + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `class BetaResponseMcpCallFailedEvent` + The Code Interpreter tool call definition. - Emitted when an MCP tool call has failed. + - `input: String` - - `item_id: String` + The input to the Code Interpreter tool call. - The ID of the MCP tool call item that failed. + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - - `output_index: Integer` + 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 index of the output item that failed. + - `class Logs` - - `sequence_number: Integer` + Text output from the Code Interpreter tool call as part of a run step. - The sequence number of this event. + - `logs: String` - - `type: :"response.mcp_call.failed"` + The text output from the Code Interpreter tool call. - The type of the event. Always 'response.mcp_call.failed'. + - `type: :logs` - - `:"response.mcp_call.failed"` + Always `logs`. - - `agent: Agent{ agent_name}` + - `:logs` - The agent that owns this multi-agent streaming event. + - `class Image` - - `agent_name: String` + - `image: Image{ file_id}` - The canonical name of the agent that produced this item. + - `file_id: String` - - `class BetaResponseMcpCallInProgressEvent` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Emitted when an MCP tool call is in progress. + - `type: :image` - - `item_id: String` + Always `image`. - The unique identifier of the MCP tool call item being processed. + - `:image` - - `output_index: Integer` + - `type: :code_interpreter` - The index of the output item in the response's output array. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `sequence_number: Integer` + - `:code_interpreter` - The sequence number of this event. + - `class FileSearchToolCall` - - `type: :"response.mcp_call.in_progress"` + - `id: String` - The type of the event. Always 'response.mcp_call.in_progress'. + The ID of the tool call object. - - `:"response.mcp_call.in_progress"` + - `file_search: FileSearch{ ranking_options, results}` - - `agent: Agent{ agent_name}` + For now, this is always going to be an empty object. - The agent that owns this multi-agent streaming event. + - `ranking_options: RankingOptions{ ranker, score_threshold}` - - `agent_name: String` + The ranking options for the file search. - The canonical name of the agent that produced this item. + - `ranker: :auto | :default_2024_08_21` - - `class BetaResponseMcpListToolsCompletedEvent` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Emitted when the list of available MCP tools has been successfully retrieved. + - `:auto` - - `item_id: String` + - `:default_2024_08_21` - The ID of the MCP tool call item that produced this output. + - `score_threshold: Float` - - `output_index: Integer` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The index of the output item that was processed. + - `results: Array[Result{ file_id, file_name, score, content}]` - - `sequence_number: Integer` + The results of the file search. - The sequence number of this event. + - `file_id: String` - - `type: :"response.mcp_list_tools.completed"` + The ID of the file that result was found in. - The type of the event. Always 'response.mcp_list_tools.completed'. + - `file_name: String` - - `:"response.mcp_list_tools.completed"` + The name of the file that result was found in. - - `agent: Agent{ agent_name}` + - `score: Float` - The agent that owns this multi-agent streaming event. + The score of the result. All values must be a floating point number between 0 and 1. - - `agent_name: String` + - `content: Array[Content{ text, type}]` - The canonical name of the agent that produced this item. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `class BetaResponseMcpListToolsFailedEvent` + - `text: String` - Emitted when the attempt to list available MCP tools has failed. + The text content of the file. - - `item_id: String` + - `type: :text` - The ID of the MCP tool call item that failed. + The type of the content. - - `output_index: Integer` + - `:text` - The index of the output item that failed. + - `type: :file_search` - - `sequence_number: Integer` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The sequence number of this event. + - `:file_search` - - `type: :"response.mcp_list_tools.failed"` + - `class FunctionToolCall` - The type of the event. Always 'response.mcp_list_tools.failed'. + - `id: String` - - `:"response.mcp_list_tools.failed"` + The ID of the tool call object. - - `agent: Agent{ agent_name}` + - `function: Function{ arguments, name, output}` - The agent that owns this multi-agent streaming event. + The definition of the function that was called. - - `agent_name: String` + - `arguments: String` - The canonical name of the agent that produced this item. + The arguments passed to the function. - - `class BetaResponseMcpListToolsInProgressEvent` + - `name: String` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The name of the function. - - `item_id: String` + - `output: String` - The ID of the MCP tool call item that is being processed. + 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. - - `output_index: Integer` + - `type: :function` - The index of the output item that is being processed. + The type of tool call. This is always going to be `function` for this type of tool call. - - `sequence_number: Integer` + - `:function` - The sequence number of this event. + - `type: :tool_calls` - - `type: :"response.mcp_list_tools.in_progress"` + Always `tool_calls`. - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `:tool_calls` - - `:"response.mcp_list_tools.in_progress"` + - `thread_id: String` - - `agent: Agent{ agent_name}` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - The agent that owns this multi-agent streaming event. + - `type: :message_creation | :tool_calls` - - `agent_name: String` + The type of run step, which can be either `message_creation` or `tool_calls`. - The canonical name of the agent that produced this item. + - `:message_creation` - - `class BetaResponseOutputTextAnnotationAddedEvent` + - `:tool_calls` - Emitted when an annotation is added to output text content. + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - - `annotation: untyped` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The annotation object being added. (See annotation schema for details.) + - `completion_tokens: Integer` - - `annotation_index: Integer` + Number of completion tokens used over the course of the run step. - The index of the annotation within the content part. + - `prompt_tokens: Integer` - - `content_index: Integer` + Number of prompt tokens used over the course of the run step. - The index of the content part within the output item. + - `total_tokens: Integer` - - `item_id: String` + Total number of tokens used (prompt + completion). - The unique identifier of the item to which the annotation is being added. + - `event: :"thread.run.step.created"` - - `output_index: Integer` + - `:"thread.run.step.created"` - The index of the output item in the response's output array. + - `class ThreadRunStepInProgress` - - `sequence_number: Integer` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - The sequence number of this event. + - `data: RunStep` - - `type: :"response.output_text.annotation.added"` + Represents a step in execution of a run. - The type of the event. Always 'response.output_text.annotation.added'. + - `event: :"thread.run.step.in_progress"` - - `:"response.output_text.annotation.added"` + - `:"thread.run.step.in_progress"` - - `agent: Agent{ agent_name}` + - `class ThreadRunStepDelta` - The agent that owns this multi-agent streaming event. + Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - `agent_name: String` + - `data: RunStepDeltaEvent` - The canonical name of the agent that produced this item. + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `class BetaResponseQueuedEvent` + - `id: String` - Emitted when a response is queued and waiting to be processed. + The identifier of the run step, which can be referenced in API endpoints. - - `response: BetaResponse` + - `delta: RunStepDelta` - The full response object that is queued. + The delta containing the fields that have changed on the run step. - - `sequence_number: Integer` + - `step_details: RunStepDeltaMessageDelta | ToolCallDeltaObject` - The sequence number for this event. + The details of the run step. - - `type: :"response.queued"` + - `class RunStepDeltaMessageDelta` - The type of the event. Always 'response.queued'. + Details of the message creation by the run step. - - `:"response.queued"` + - `type: :message_creation` - - `agent: Agent{ agent_name}` + Always `message_creation`. - The agent that owns this multi-agent streaming event. + - `:message_creation` - - `agent_name: String` + - `message_creation: MessageCreation{ message_id}` - The canonical name of the agent that produced this item. + - `message_id: String` - - `class BetaResponseCustomToolCallInputDeltaEvent` + The ID of the message that was created by this run step. - Event representing a delta (partial update) to the input of a custom tool call. + - `class ToolCallDeltaObject` - - `delta: String` + Details of the tool call. - The incremental input data (delta) for the custom tool call. + - `type: :tool_calls` - - `item_id: String` + Always `tool_calls`. - Unique identifier for the API item associated with this event. + - `:tool_calls` - - `output_index: Integer` + - `tool_calls: Array[ToolCallDelta]` - The index of the output this delta applies to. + 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`. - - `sequence_number: Integer` + - `class CodeInterpreterToolCallDelta` - The sequence number of this event. + Details of the Code Interpreter tool call the run step was involved in. - - `type: :"response.custom_tool_call_input.delta"` + - `index: Integer` - The event type identifier. + The index of the tool call in the tool calls array. - - `:"response.custom_tool_call_input.delta"` + - `type: :code_interpreter` - - `agent: Agent{ agent_name}` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The agent that owns this multi-agent streaming event. + - `:code_interpreter` - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The ID of the tool call. - - `class BetaResponseCustomToolCallInputDoneEvent` + - `code_interpreter: CodeInterpreter{ input, outputs}` - Event indicating that input for a custom tool call is complete. + The Code Interpreter tool call definition. - `input: String` - The complete input data for the custom tool call. + The input to the Code Interpreter tool call. - - `item_id: String` + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - Unique identifier for the API item associated with this event. + 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. - - `output_index: Integer` + - `class CodeInterpreterLogs` - The index of the output this event applies to. + Text output from the Code Interpreter tool call as part of a run step. - - `sequence_number: Integer` + - `index: Integer` - The sequence number of this event. + The index of the output in the outputs array. - - `type: :"response.custom_tool_call_input.done"` + - `type: :logs` - The event type identifier. + Always `logs`. - - `:"response.custom_tool_call_input.done"` + - `:logs` - - `agent: Agent{ agent_name}` + - `logs: String` - The agent that owns this multi-agent streaming event. + The text output from the Code Interpreter tool call. - - `agent_name: String` + - `class CodeInterpreterOutputImage` - The canonical name of the agent that produced this item. + - `index: Integer` - - `class ResponseInjectCreated` + The index of the output in the outputs array. - Emitted when all injected input items were validated and committed to the - active response. + - `type: :image` - - `response_id: String` + Always `image`. - The ID of the response that accepted the input. + - `:image` - - `sequence_number: Integer` + - `image: Image{ file_id}` - The sequence number for this event. + - `file_id: String` - - `type: :"response.inject.created"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The event discriminator. Always `response.inject.created`. + - `class FileSearchToolCallDelta` - - `:"response.inject.created"` + - `file_search: untyped` - - `stream_id: String` + For now, this is always going to be an empty object. - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `index: Integer` - - `class ResponseInjectFailed` + The index of the tool call in the tool calls array. - 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. + - `type: :file_search` - - `error: Error{ code, message}` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Information about why the input was not committed. + - `:file_search` - - `code: :response_already_completed | :response_not_found` + - `id: String` - A machine-readable error code. + The ID of the tool call object. - - `:response_already_completed` + - `class FunctionToolCallDelta` - - `:response_not_found` + - `index: Integer` - - `message: String` + The index of the tool call in the tool calls array. - A human-readable description of the error. + - `type: :function` - - `input: Array[BetaResponseInputItem]` + The type of tool call. This is always going to be `function` for this type of tool call. - The raw input items that were not committed. + - `:function` - - `class BetaEasyInputMessage` + - `id: String` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The ID of the tool call object. - - `class Message` + - `function: Function{ arguments, name, output}` - 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 definition of the function that was called. - - `class BetaResponseOutputMessage` + - `arguments: String` - An output message from the model. + The arguments passed to the function. - - `class BetaResponseFileSearchToolCall` + - `name: String` - 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 name of the function. - - `class BetaResponseComputerToolCall` + - `output: 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. + 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. - - `class ComputerCallOutput` + - `object: :"thread.run.step.delta"` - The output of a computer tool call. + The object type, which is always `thread.run.step.delta`. - - `class BetaResponseFunctionWebSearch` + - `:"thread.run.step.delta"` - 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.run.step.delta"` - - `class BetaResponseFunctionToolCall` + - `:"thread.run.step.delta"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class ThreadRunStepCompleted` - - `class FunctionCallOutput` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - The output of a function tool call. + - `data: RunStep` - - `class AgentMessage` + Represents a step in execution of a run. - A message routed between agents. + - `event: :"thread.run.step.completed"` - - `class MultiAgentCall` + - `:"thread.run.step.completed"` - - `class MultiAgentCallOutput` + - `class ThreadRunStepFailed` - - `class ToolSearchCall` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - - `class BetaResponseToolSearchOutputItemParam` + - `data: RunStep` - - `class AdditionalTools` + Represents a step in execution of a run. - - `class BetaResponseReasoningItem` + - `event: :"thread.run.step.failed"` - 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). + - `:"thread.run.step.failed"` - - `class BetaResponseCompactionItemParam` + - `class ThreadRunStepCancelled` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - - `class ImageGenerationCall` + - `data: RunStep` - An image generation request made by the model. + Represents a step in execution of a run. - - `class BetaResponseCodeInterpreterToolCall` + - `event: :"thread.run.step.cancelled"` - A tool call to run code. + - `:"thread.run.step.cancelled"` - - `class LocalShellCall` + - `class ThreadRunStepExpired` - A tool call to run a command on the local shell. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - - `class LocalShellCallOutput` + - `data: RunStep` - The output of a local shell tool call. + Represents a step in execution of a run. - - `class ShellCall` + - `event: :"thread.run.step.expired"` - A tool representing a request to execute one or more shell commands. + - `:"thread.run.step.expired"` - - `class ShellCallOutput` + - `class ThreadMessageCreated` - The streamed output items emitted by a shell tool call. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - `class ApplyPatchCall` + - `data: Message` - A tool call representing a request to create, delete, or update files using diff patches. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class ApplyPatchCallOutput` + - `id: String` - The streamed output emitted by an apply patch tool call. + The identifier, which can be referenced in API endpoints. - - `class McpListTools` + - `assistant_id: String` - A list of tools available on an MCP server. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `class McpApprovalRequest` + - `attachments: Array[Attachment{ file_id, tools}]` - A request for human approval of a tool invocation. + A list of files attached to the message, and the tools they were added to. - - `class McpApprovalResponse` + - `file_id: String` - A response to an MCP approval request. + The ID of the file to attach to the message. - - `class McpCall` + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - An invocation of a tool on an MCP server. + The tools to add this file to. - - `class BetaResponseCustomToolCallOutput` + - `class CodeInterpreterTool` - The output of a custom tool call from your code, being sent back to the model. + - `class AssistantToolsFileSearchTypeOnly` - - `class BetaResponseCustomToolCall` + - `type: :file_search` - A call to a custom tool created by the model. + The type of tool being defined: `file_search` - - `class CompactionTrigger` + - `:file_search` - Compacts the current context. Must be the final input item. + - `completed_at: Integer` - - `class ItemReference` + The Unix timestamp (in seconds) for when the message was completed. - An internal identifier for an item to reference. + - `content: Array[MessageContent]` - - `class Program` + The content of the message in array of text and/or images. - - `class ProgramOutput` + - `class ImageFileContentBlock` - - `response_id: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The ID of the response that rejected the input. + - `image_file: ImageFile` - - `sequence_number: Integer` + - `file_id: String` - The sequence number for this event. + 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: :"response.inject.failed"` + - `detail: :auto | :low | :high` - The event discriminator. Always `response.inject.failed`. + 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`. - - `:"response.inject.failed"` + - `:auto` - - `stream_id: String` + - `:low` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `:high` -### Beta Skill Reference + - `type: :image_file` -- `class BetaSkillReference` + Always `image_file`. - - `skill_id: String` + - `:image_file` - The ID of the referenced skill. + - `class ImageURLContentBlock` - - `type: :skill_reference` + References an image URL in the content of a message. - References a skill created with the /v1/skills endpoint. + - `image_url: ImageURL` - - `:skill_reference` + - `url: String` - - `version: String` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `detail: :auto | :low | :high` -### Beta Tool + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` -- `BetaTool = BetaFunctionTool | BetaFileSearchTool | BetaComputerTool | 13 more` + - `:auto` - A tool that can be used to generate a response. + - `:low` - - `class BetaFunctionTool` + - `:high` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `type: :image_url` - - `name: String` + The type of the content part. - The name of the function to call. + - `:image_url` - - `parameters: Hash[Symbol, untyped]` + - `class TextContentBlock` - A JSON schema object describing the parameters of the function. + The text content that is part of a message. - - `strict: bool` + - `text: Text` - Whether strict parameter validation is enforced for this function tool. + - `annotations: Array[Annotation]` - - `type: :function` + - `class FileCitationAnnotation` - The type of the function tool. Always `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. - - `:function` + - `end_index: Integer` - - `allowed_callers: Array[:direct | :programmatic]` + - `file_citation: FileCitation{ file_id}` - The tool invocation context(s). + - `file_id: String` - - `:direct` + The ID of the specific File the citation is from. - - `:programmatic` + - `start_index: Integer` - - `defer_loading: bool` + - `text: String` - Whether this function is deferred and loaded via tool search. + The text in the message content that needs to be replaced. - - `description: String` + - `type: :file_citation` - A description of the function. Used by the model to determine whether or not to call the function. + Always `file_citation`. - - `output_schema: Hash[Symbol, untyped]` + - `:file_citation` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FilePathAnnotation` - - `class BetaFileSearchTool` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - 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). + - `end_index: Integer` - - `type: :file_search` + - `file_path: FilePath{ file_id}` - The type of the file search tool. Always `file_search`. + - `file_id: String` - - `:file_search` + The ID of the file that was generated. - - `vector_store_ids: Array[String]` + - `start_index: Integer` - The IDs of the vector stores to search. + - `text: String` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + The text in the message content that needs to be replaced. - A filter to apply. + - `type: :file_path` - - `class ComparisonFilter` + Always `file_path`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `:file_path` - - `key: String` + - `value: String` - The key to compare against the value. + The data that makes up the text. - - `type: :eq | :ne | :gt | 5 more` + - `type: :text` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Always `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` - - `:eq` + - `class RefusalContentBlock` - - `:ne` + The refusal content generated by the assistant. - - `:gt` + - `refusal: String` - - `:gte` + - `type: :refusal` - - `:lt` + Always `refusal`. - - `:lte` + - `:refusal` - - `:in` + - `created_at: Integer` - - `:nin` + The Unix timestamp (in seconds) for when the message was created. - - `value: String | Float | bool | Array[untyped]` + - `incomplete_at: Integer` - The value to compare against the attribute key; supports string, number, or boolean types. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `String = String` + - `incomplete_details: IncompleteDetails{ reason}` - - `Float = Float` + On an incomplete message, details about why the message is incomplete. - - `UnionMember2 = bool` + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - - `UnionMember3 = Array[untyped]` + The reason the message is incomplete. - - `class CompoundFilter` + - `:content_filter` - Combine multiple filters using `and` or `or`. + - `:max_tokens` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + - `:run_cancelled` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `:run_expired` - - `class ComparisonFilter` + - `:run_failed` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `metadata: Metadata` - - `key: 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 key to compare against the value. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: :eq | :ne | :gt | 5 more` + - `object: :"thread.message"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The object type, which is always `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 + - `:"thread.message"` - - `:eq` + - `role: :user | :assistant` - - `:ne` + The entity that produced the message. One of `user` or `assistant`. - - `:gt` + - `:user` - - `:gte` + - `:assistant` - - `:lt` + - `run_id: String` - - `:lte` + 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. - - `:in` + - `status: :in_progress | :incomplete | :completed` - - `:nin` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `value: String | Float | bool | Array[untyped]` + - `:in_progress` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:incomplete` - - `String = String` + - `:completed` - - `Float = Float` + - `thread_id: String` - - `UnionMember2 = bool` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `UnionMember3 = Array[untyped]` + - `event: :"thread.message.created"` - - `UnionMember1 = untyped` + - `:"thread.message.created"` - - `type: :and | :or` + - `class ThreadMessageInProgress` - Type of operation: `and` or `or`. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - - `:and` + - `data: Message` - - `:or` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `max_num_results: Integer` + - `event: :"thread.message.in_progress"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `:"thread.message.in_progress"` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `class ThreadMessageDelta` - Ranking options for search. + Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + - `data: MessageDeltaEvent` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Represents a message delta i.e. any changed fields on a message during streaming. - - `embedding_weight: Float` + - `id: String` - The weight of the embedding in the reciprocal ranking fusion. + The identifier of the message, which can be referenced in API endpoints. - - `text_weight: Float` + - `delta: MessageDelta` - The weight of the text in the reciprocal ranking fusion. + The delta containing the fields that have changed on the Message. - - `ranker: :auto | :"default-2024-11-15"` + - `content: Array[MessageContentDelta]` - The ranker to use for the file search. + The content of the message in array of text and/or images. - - `:auto` + - `class ImageFileDeltaBlock` - - `:"default-2024-11-15"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `score_threshold: Float` + - `index: Integer` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The index of the content part in the message. - - `class BetaComputerTool` + - `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). + Always `image_file`. - - `type: :computer` + - `:image_file` - The type of the computer tool. Always `computer`. + - `image_file: ImageFileDelta` - - `:computer` + - `detail: :auto | :low | :high` - - `class BetaComputerUsePreviewTool` + 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: Integer` + - `:low` - The height of the computer display. + - `:high` - - `display_width: Integer` + - `file_id: String` - The width of the computer display. + 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: :windows | :mac | :linux | 2 more` + - `class TextDeltaBlock` - The type of computer environment to control. + The text content that is part of a message. - - `:windows` + - `index: Integer` - - `:mac` + The index of the content part in the message. - - `:linux` + - `type: :text` - - `:ubuntu` + Always `text`. - - `:browser` + - `:text` - - `type: :computer_use_preview` + - `text: TextDelta` - The type of the computer use tool. Always `computer_use_preview`. + - `annotations: Array[AnnotationDelta]` - - `:computer_use_preview` + - `class FileCitationDeltaAnnotation` - - `class BetaWebSearchTool` + 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. - 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). + - `index: Integer` - - `type: :web_search | :web_search_2025_08_26` + The index of the annotation in the text content part. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: :file_citation` - - `:web_search` + Always `file_citation`. - - `:web_search_2025_08_26` + - `:file_citation` - - `filters: Filters{ allowed_domains}` + - `end_index: Integer` - Filters for the search. + - `file_citation: FileCitation{ file_id, quote}` - - `allowed_domains: Array[String]` + - `file_id: String` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The ID of the specific File the citation is from. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `quote: String` - - `search_context_size: :low | :medium | :high` + The specific quote in 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. + - `start_index: Integer` - - `:low` + - `text: String` - - `:medium` + The text in the message content that needs to be replaced. - - `:high` + - `class FilePathDeltaAnnotation` - - `user_location: UserLocation{ city, country, region, 2 more}` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The approximate location of the user. + - `index: Integer` - - `city: String` + The index of the annotation in the text content part. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: :file_path` - - `country: String` + Always `file_path`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `:file_path` - - `region: String` + - `end_index: Integer` - Free text input for the region of the user, e.g. `California`. + - `file_path: FilePath{ file_id}` - - `timezone: String` + - `file_id: String` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ID of the file that was generated. - - `type: :approximate` + - `start_index: Integer` - The type of location approximation. Always `approximate`. + - `text: String` - - `:approximate` + The text in the message content that needs to be replaced. - - `class Mcp` + - `value: 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 data that makes up the text. - - `server_label: String` + - `class RefusalDeltaBlock` - A label for this MCP server, used to identify it in tool calls. + The refusal content that is part of a message. - - `type: :mcp` + - `index: Integer` - The type of the MCP tool. Always `mcp`. + The index of the refusal part in the message. - - `:mcp` + - `type: :refusal` - - `allowed_callers: Array[:direct | :programmatic]` + Always `refusal`. - The tool invocation context(s). + - `:refusal` - - `:direct` + - `refusal: String` - - `:programmatic` + - `class ImageURLDeltaBlock` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + References an image URL in the content of a message. - List of allowed tool names or a filter object. + - `index: Integer` - - `McpAllowedTools = Array[String]` + The index of the content part in the message. - A string array of allowed tool names + - `type: :image_url` - - `class McpToolFilter` + Always `image_url`. - A filter object to specify which tools are allowed. + - `:image_url` - - `read_only: bool` + - `image_url: ImageURLDelta` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `detail: :auto | :low | :high` - - `tool_names: Array[String]` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - List of allowed tool names. + - `:auto` - - `authorization: String` + - `:low` - 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. + - `:high` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Currently supported `connector_id` values are: + - `role: :user | :assistant` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The entity that produced the message. One of `user` or `assistant`. - - `:connector_dropbox` + - `:user` - - `:connector_gmail` + - `:assistant` - - `:connector_googlecalendar` + - `object: :"thread.message.delta"` - - `:connector_googledrive` + The object type, which is always `thread.message.delta`. - - `:connector_microsoftteams` + - `:"thread.message.delta"` - - `:connector_outlookcalendar` + - `event: :"thread.message.delta"` - - `:connector_outlookemail` + - `:"thread.message.delta"` - - `:connector_sharepoint` + - `class ThreadMessageCompleted` - - `defer_loading: bool` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - Whether this MCP tool is deferred and discovered via tool search. + - `data: Message` - - `headers: Hash[Symbol, String]` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `event: :"thread.message.completed"` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:"thread.message.completed"` - Specify which of the MCP server's tools require approval. + - `class ThreadMessageIncomplete` - - `class McpToolApprovalFilter` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is 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. + - `data: Message` - - `always: Always{ read_only, tool_names}` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - A filter object to specify which tools are allowed. + - `event: :"thread.message.incomplete"` - - `read_only: bool` + - `:"thread.message.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. + - `class ErrorEvent` - - `tool_names: Array[String]` + 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. - List of allowed tool names. + - `data: ErrorObject` - - `never: Never{ read_only, tool_names}` + - `code: String` - A filter object to specify which tools are allowed. + - `message: String` - - `read_only: bool` + - `param: 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. + - `type: String` - - `tool_names: Array[String]` + - `event: :error` - List of allowed tool names. + - `:error` - - `McpToolApprovalSetting = :always | :never` +### Assistant 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. +- `AssistantTool = CodeInterpreterTool | FileSearchTool | FunctionTool` - - `:always` + - `class CodeInterpreterTool` + + - `type: :code_interpreter` + + The type of tool being defined: `code_interpreter` - - `:never` + - `:code_interpreter` - - `server_description: String` + - `class FileSearchTool` - Optional description of the MCP server, used to provide more context. + - `type: :file_search` - - `server_url: String` + The type of tool being defined: `file_search` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:file_search` - - `tunnel_id: String` + - `file_search: FileSearch{ max_num_results, ranking_options}` - 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. + Overrides for the file search tool. - - `class CodeInterpreter` + - `max_num_results: Integer` - A tool that runs Python code to help generate a response to a prompt. + 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. - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + 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 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. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `String = 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 container ID. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class CodeInterpreterToolAuto` + - `score_threshold: Float` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: :auto` + - `ranker: :auto | :default_2024_08_21` - Always `auto`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - `:auto` - - `file_ids: Array[String]` - - An optional list of uploaded files to make available to your code. + - `:default_2024_08_21` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class FunctionTool` - The memory limit for the code interpreter container. + - `function: FunctionDefinition` - - `:"1g"` + - `name: String` - - `:"4g"` + 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. - - `:"16g"` + - `description: String` - - `:"64g"` + A description of what the function does, used by the model to choose when and how to call the function. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `parameters: FunctionParameters` - Network access policy for the container. + 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. - - `class BetaContainerNetworkPolicyDisabled` + Omitting `parameters` defines a function with an empty parameter list. - - `type: :disabled` + - `strict: bool` - Disable outbound network access. Always `disabled`. + 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). - - `:disabled` + - `type: :function` - - `class BetaContainerNetworkPolicyAllowlist` + The type of tool being defined: `function` - - `allowed_domains: Array[String]` + - `:function` - A list of allowed domains when type is `allowlist`. +### Code Interpreter Tool - - `type: :allowlist` +- `class CodeInterpreterTool` - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: :code_interpreter` - - `:allowlist` + The type of tool being defined: `code_interpreter` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `:code_interpreter` - Optional domain-scoped secrets for allowlisted domains. +### File Search Tool - - `domain: String` +- `class FileSearchTool` - The domain associated with the secret. + - `type: :file_search` - - `name: String` + The type of tool being defined: `file_search` - The name of the secret to inject for the domain. + - `:file_search` - - `value: String` + - `file_search: FileSearch{ max_num_results, ranking_options}` - The secret value to inject for the domain. + Overrides for the file search tool. - - `type: :code_interpreter` + - `max_num_results: Integer` - The type of the code interpreter tool. Always `code_interpreter`. + 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. - - `:code_interpreter` + 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. - - `allowed_callers: Array[:direct | :programmatic]` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - The tool invocation context(s). + 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. - - `:direct` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `:programmatic` + - `score_threshold: Float` - - `class ProgrammaticToolCalling` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: :programmatic_tool_calling` + - `ranker: :auto | :default_2024_08_21` - The type of the tool. Always `programmatic_tool_calling`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `:programmatic_tool_calling` + - `:auto` - - `class ImageGeneration` + - `:default_2024_08_21` - A tool that generates images using the GPT image models. +### Function Tool - - `type: :image_generation` +- `class FunctionTool` - The type of the image generation tool. Always `image_generation`. + - `function: FunctionDefinition` - - `:image_generation` + - `name: String` - - `action: :generate | :edit | :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. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `description: String` - - `:generate` + A description of what the function does, used by the model to choose when and how to call the function. - - `:edit` + - `parameters: FunctionParameters` - - `:auto` + 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. - - `background: :transparent | :opaque | :auto` + Omitting `parameters` defines a function with an empty parameter list. - 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. + - `strict: bool` - `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. + 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). - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: :function` - - `:transparent` + The type of tool being defined: `function` - - `:opaque` + - `:function` - - `:auto` +### Message Stream Event - - `input_fidelity: :high | :low` +- `MessageStreamEvent = ThreadMessageCreated{ data, event} | ThreadMessageInProgress{ data, event} | ThreadMessageDelta{ data, event} | 2 more` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - `:high` + - `class ThreadMessageCreated` - - `:low` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `data: Message` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `file_id: String` + - `id: String` - File ID for the mask image. + The identifier, which can be referenced in API endpoints. - - `image_url: String` + - `assistant_id: String` - Base64-encoded mask image. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `attachments: Array[Attachment{ file_id, tools}]` - The image generation model to use. Default: `gpt-image-1`. + A list of files attached to the message, and the tools they were added to. - - `String = String` + - `file_id: String` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + The ID of the file to attach to the message. - The image generation model to use. Default: `gpt-image-1`. + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - - `:"gpt-image-1"` + The tools to add this file to. - - `:"gpt-image-1-mini"` + - `class CodeInterpreterTool` - - `:"gpt-image-2"` + - `type: :code_interpreter` - - `:"gpt-image-2-2026-04-21"` + The type of tool being defined: `code_interpreter` - - `:"gpt-image-1.5"` + - `:code_interpreter` - - `:"chatgpt-image-latest"` + - `class AssistantToolsFileSearchTypeOnly` - - `moderation: :auto | :low` + - `type: :file_search` - Moderation level for the generated image. Default: `auto`. + The type of tool being defined: `file_search` - - `:auto` + - `:file_search` - - `:low` + - `completed_at: Integer` - - `output_compression: Integer` + The Unix timestamp (in seconds) for when the message was completed. - Compression level for the output image. Default: 100. + - `content: Array[MessageContent]` - - `output_format: :png | :webp | :jpeg` + The content of the message in array of text and/or images. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `class ImageFileContentBlock` - - `:png` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `:webp` + - `image_file: ImageFile` - - `:jpeg` + - `file_id: String` - - `partial_images: Integer` + 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. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `detail: :auto | :low | :high` - - `quality: :low | :medium | :high | :auto` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `:auto` - `:low` - - `:medium` - - `:high` - - `:auto` + - `type: :image_file` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + Always `image_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`. + - `:image_file` - - `String = String` + - `class ImageURLContentBlock` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + References an image URL in the content of a 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`. + - `image_url: ImageURL` - - `:"1024x1024"` + - `url: String` - - `:"1024x1536"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `:"1536x1024"` + - `detail: :auto | :low | :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` - `:auto` - - `class LocalShell` + - `:low` - A tool that allows the model to execute shell commands in a local environment. + - `:high` - - `type: :local_shell` + - `type: :image_url` - The type of the local shell tool. Always `local_shell`. + The type of the content part. - - `:local_shell` + - `:image_url` - - `class BetaFunctionShellTool` + - `class TextContentBlock` - A tool that allows the model to execute shell commands. + The text content that is part of a message. - - `type: :shell` + - `text: Text` - The type of the shell tool. Always `shell`. + - `annotations: Array[Annotation]` - - `:shell` + - `class FileCitationAnnotation` - - `allowed_callers: Array[:direct | :programmatic]` + 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 tool invocation context(s). + - `end_index: Integer` - - `:direct` + - `file_citation: FileCitation{ file_id}` - - `:programmatic` + - `file_id: String` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + The ID of the specific File the citation is from. - - `class BetaContainerAuto` + - `start_index: Integer` - - `type: :container_auto` + - `text: String` - Automatically creates a container for this request + The text in the message content that needs to be replaced. - - `:container_auto` + - `type: :file_citation` - - `file_ids: Array[String]` + Always `file_citation`. - An optional list of uploaded files to make available to your code. + - `:file_citation` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class FilePathAnnotation` - The memory limit for the container. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `:"1g"` + - `end_index: Integer` - - `:"4g"` + - `file_path: FilePath{ file_id}` - - `:"16g"` + - `file_id: String` - - `:"64g"` + The ID of the file that was generated. - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `start_index: Integer` - Network access policy for the container. + - `text: String` - - `class BetaContainerNetworkPolicyDisabled` + The text in the message content that needs to be replaced. - - `class BetaContainerNetworkPolicyAllowlist` + - `type: :file_path` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + Always `file_path`. - An optional list of skills referenced by id or inline data. + - `:file_path` - - `class BetaSkillReference` + - `value: String` - - `skill_id: String` + The data that makes up the text. - The ID of the referenced skill. + - `type: :text` - - `type: :skill_reference` + Always `text`. - References a skill created with the /v1/skills endpoint. + - `:text` - - `:skill_reference` + - `class RefusalContentBlock` - - `version: String` + The refusal content generated by the assistant. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `refusal: String` - - `class BetaInlineSkill` + - `type: :refusal` - - `description: String` + Always `refusal`. - The description of the skill. + - `:refusal` - - `name: String` + - `created_at: Integer` - The name of the skill. + The Unix timestamp (in seconds) for when the message was created. - - `source: BetaInlineSkillSource` + - `incomplete_at: Integer` - Inline skill payload + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `data: String` + - `incomplete_details: IncompleteDetails{ reason}` - Base64-encoded skill zip bundle. + On an incomplete message, details about why the message is incomplete. - - `media_type: :"application/zip"` + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - The media type of the inline skill payload. Must be `application/zip`. + The reason the message is incomplete. - - `:"application/zip"` + - `:content_filter` - - `type: :base64` + - `:max_tokens` - The type of the inline skill source. Must be `base64`. + - `:run_cancelled` - - `:base64` + - `:run_expired` - - `type: :inline` + - `:run_failed` - Defines an inline skill for this request. + - `metadata: Metadata` - - `:inline` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class BetaLocalEnvironment` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: :local` + - `object: :"thread.message"` - Use a local computer environment. + The object type, which is always `thread.message`. - - `:local` + - `:"thread.message"` - - `skills: Array[BetaLocalSkill]` + - `role: :user | :assistant` - An optional list of skills. + The entity that produced the message. One of `user` or `assistant`. - - `description: String` + - `:user` - The description of the skill. + - `:assistant` - - `name: String` + - `run_id: String` - The name of the skill. + 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. - - `path: String` + - `status: :in_progress | :incomplete | :completed` - The path to the directory containing the skill. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `class BetaContainerReference` + - `:in_progress` - - `container_id: String` + - `:incomplete` - The ID of the referenced container. + - `:completed` - - `type: :container_reference` + - `thread_id: String` - References a container created with the /v1/containers endpoint + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `:container_reference` + - `event: :"thread.message.created"` - - `class BetaCustomTool` + - `:"thread.message.created"` - 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) + - `class ThreadMessageInProgress` - - `name: String` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - The name of the custom tool, used to identify it in tool calls. + - `data: Message` - - `type: :custom` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the custom tool. Always `custom`. + - `event: :"thread.message.in_progress"` - - `:custom` + - `:"thread.message.in_progress"` - - `allowed_callers: Array[:direct | :programmatic]` + - `class ThreadMessageDelta` - The tool invocation context(s). + Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - `:direct` + - `data: MessageDeltaEvent` - - `:programmatic` + Represents a message delta i.e. any changed fields on a message during streaming. - - `defer_loading: bool` + - `id: String` - Whether this tool should be deferred and discovered via tool search. + The identifier of the message, which can be referenced in API endpoints. - - `description: String` + - `delta: MessageDelta` - Optional description of the custom tool, used to provide more context. + The delta containing the fields that have changed on the Message. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `content: Array[MessageContentDelta]` - The input format for the custom tool. Default is unconstrained text. + The content of the message in array of text and/or images. - - `class Text` + - `class ImageFileDeltaBlock` - Unconstrained free-form text. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `type: :text` + - `index: Integer` - Unconstrained text format. Always `text`. + The index of the content part in the message. - - `:text` + - `type: :image_file` - - `class Grammar` + Always `image_file`. - A grammar defined by the user. + - `:image_file` - - `definition: String` + - `image_file: ImageFileDelta` - The grammar definition. + - `detail: :auto | :low | :high` - - `syntax: :lark | :regex` + 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 syntax of the grammar definition. One of `lark` or `regex`. + - `:auto` - - `:lark` + - `:low` - - `:regex` + - `:high` - - `type: :grammar` + - `file_id: String` - Grammar format. Always `grammar`. + 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. - - `:grammar` + - `class TextDeltaBlock` - - `class BetaNamespaceTool` + The text content that is part of a message. - Groups function/custom tools under a shared namespace. + - `index: Integer` - - `description: String` + The index of the content part in the message. - A description of the namespace shown to the model. + - `type: :text` - - `name: String` + Always `text`. - The namespace name used in tool calls (for example, `crm`). + - `:text` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `text: TextDelta` - The function/custom tools available inside this namespace. + - `annotations: Array[AnnotationDelta]` - - `class Function` + - `class FileCitationDeltaAnnotation` - - `name: String` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `type: :function` + - `index: Integer` - - `:function` + The index of the annotation in the text content part. - - `allowed_callers: Array[:direct | :programmatic]` + - `type: :file_citation` - The tool invocation context(s). + Always `file_citation`. - - `:direct` + - `:file_citation` - - `:programmatic` + - `end_index: Integer` - - `defer_loading: bool` + - `file_citation: FileCitation{ file_id, quote}` - Whether this function should be deferred and discovered via tool search. + - `file_id: String` - - `description: String` + The ID of the specific File the citation is from. - - `output_schema: Hash[Symbol, untyped]` + - `quote: String` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The specific quote in the file. - - `parameters: untyped` + - `start_index: Integer` - - `strict: bool` + - `text: 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 text in the message content that needs to be replaced. - - `class BetaCustomTool` + - `class FilePathDeltaAnnotation` - 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 URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `type: :namespace` + - `index: Integer` - The type of the tool. Always `namespace`. + The index of the annotation in the text content part. - - `:namespace` + - `type: :file_path` - - `class BetaToolSearchTool` + Always `file_path`. - Hosted or BYOT tool search configuration for deferred tools. + - `:file_path` - - `type: :tool_search` + - `end_index: Integer` - The type of the tool. Always `tool_search`. + - `file_path: FilePath{ file_id}` - - `:tool_search` + - `file_id: String` - - `description: String` + The ID of the file that was generated. - Description shown to the model for a client-executed tool search tool. + - `start_index: Integer` - - `execution: :server | :client` + - `text: String` - Whether tool search is executed by the server or by the client. + The text in the message content that needs to be replaced. - - `:server` + - `value: String` - - `:client` + The data that makes up the text. - - `parameters: untyped` + - `class RefusalDeltaBlock` - Parameter schema for a client-executed tool search tool. + The refusal content that is part of a message. - - `class BetaWebSearchPreviewTool` + - `index: Integer` - 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 refusal part in the message. - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `type: :refusal` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Always `refusal`. - - `:web_search_preview` + - `:refusal` - - `:web_search_preview_2025_03_11` + - `refusal: String` - - `search_content_types: Array[:text | :image]` + - `class ImageURLDeltaBlock` - - `:text` + References an image URL in the content of a message. - - `:image` + - `index: Integer` - - `search_context_size: :low | :medium | :high` + The index of the content part in the message. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `type: :image_url` - - `:low` + Always `image_url`. - - `:medium` + - `:image_url` - - `:high` + - `image_url: ImageURLDelta` - - `user_location: UserLocation{ type, city, country, 2 more}` + - `detail: :auto | :low | :high` - The user's location. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `type: :approximate` + - `:auto` - The type of location approximation. Always `approximate`. + - `:low` - - `:approximate` + - `:high` - - `city: String` + - `url: String` - Free text input for the city of the user, e.g. `San Francisco`. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `country: String` + - `role: :user | :assistant` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The entity that produced the message. One of `user` or `assistant`. - - `region: String` + - `:user` - Free text input for the region of the user, e.g. `California`. + - `:assistant` - - `timezone: String` + - `object: :"thread.message.delta"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The object type, which is always `thread.message.delta`. - - `class BetaApplyPatchTool` + - `:"thread.message.delta"` - Allows the assistant to create, delete, or update files using unified diffs. + - `event: :"thread.message.delta"` - - `type: :apply_patch` + - `:"thread.message.delta"` - The type of the tool. Always `apply_patch`. + - `class ThreadMessageCompleted` - - `:apply_patch` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - - `allowed_callers: Array[:direct | :programmatic]` + - `data: Message` - The tool invocation context(s). + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `:direct` + - `event: :"thread.message.completed"` - - `:programmatic` + - `:"thread.message.completed"` -### Beta Tool Choice Allowed + - `class ThreadMessageIncomplete` -- `class BetaToolChoiceAllowed` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - Constrains the tools available to the model to a pre-defined set. + - `data: Message` - - `mode: :auto | :required` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - Constrains the tools available to the model to a pre-defined set. + - `event: :"thread.message.incomplete"` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `:"thread.message.incomplete"` - `required` requires the model to call one or more of the allowed tools. +### Run Step Stream Event - - `:auto` +- `RunStepStreamEvent = ThreadRunStepCreated{ data, event} | ThreadRunStepInProgress{ data, event} | ThreadRunStepDelta{ data, event} | 4 more` - - `:required` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `tools: Array[Hash[Symbol, untyped]]` + - `class ThreadRunStepCreated` - 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 created. - 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` + - `id: String` - Allowed tool configuration type. Always `allowed_tools`. + The identifier of the run step, which can be referenced in API endpoints. - - `:allowed_tools` + - `assistant_id: String` -### Beta Tool Choice Apply Patch + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. -- `class BetaToolChoiceApplyPatch` + - `cancelled_at: Integer` - Forces the model to call the apply_patch tool when executing a tool call. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `type: :apply_patch` + - `completed_at: Integer` - The tool to call. Always `apply_patch`. + The Unix timestamp (in seconds) for when the run step completed. - - `:apply_patch` + - `created_at: Integer` -### Beta Tool Choice Custom + The Unix timestamp (in seconds) for when the run step was created. -- `class BetaToolChoiceCustom` + - `expired_at: Integer` - Use this option to force the model to call a specific custom tool. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `name: String` + - `failed_at: Integer` - The name of the custom tool to call. + The Unix timestamp (in seconds) for when the run step failed. - - `type: :custom` + - `last_error: LastError{ code, message}` - For custom tool calling, the type is always `custom`. + The last error associated with this run step. Will be `null` if there are no errors. - - `:custom` + - `code: :server_error | :rate_limit_exceeded` -### Beta Tool Choice Function + One of `server_error` or `rate_limit_exceeded`. -- `class BetaToolChoiceFunction` + - `:server_error` - Use this option to force the model to call a specific function. + - `:rate_limit_exceeded` - - `name: String` + - `message: String` - The name of the function to call. + A human-readable description of the error. - - `type: :function` + - `metadata: Metadata` - For function calling, the type is always `function`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `:function` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. -### Beta Tool Choice Mcp + - `object: :"thread.run.step"` -- `class BetaToolChoiceMcp` + The object type, which is always `thread.run.step`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `:"thread.run.step"` - - `server_label: String` + - `run_id: String` - The label of the MCP server to use. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `type: :mcp` + - `status: :in_progress | :cancelled | :failed | 2 more` - For MCP tools, the type is always `mcp`. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `:mcp` + - `:in_progress` - - `name: String` + - `:cancelled` - The name of the tool to call on the server. + - `:failed` -### Beta Tool Choice Options + - `:completed` -- `BetaToolChoiceOptions = :none | :auto | :required` + - `:expired` - Controls which (if any) tool is called by the model. + - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` - `none` means the model will not call any tool and instead generates a message. + The details of the run step. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `class MessageCreationStepDetails` - `required` means the model must call one or more tools. + Details of the message creation by the run step. - - `:none` + - `message_creation: MessageCreation{ message_id}` - - `:auto` + - `message_id: String` - - `:required` + The ID of the message that was created by this run step. -### Beta Tool Choice Shell + - `type: :message_creation` -- `class BetaToolChoiceShell` + Always `message_creation`. - Forces the model to call the shell tool when a tool call is required. + - `:message_creation` - - `type: :shell` + - `class ToolCallsStepDetails` - The tool to call. Always `shell`. + Details of the tool call. - - `:shell` + - `tool_calls: Array[ToolCall]` -### Beta Tool Choice Types + 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`. -- `class BetaToolChoiceTypes` + - `class CodeInterpreterToolCall` - 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). + Details of the Code Interpreter tool call the run step was involved in. - - `type: :file_search | :web_search_preview | :computer | 5 more` + - `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 tool call. - Allowed values are: + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The Code Interpreter tool call definition. - - `:file_search` + - `input: String` - - `:web_search_preview` + The input to the Code Interpreter tool call. - - `:computer` + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - - `:computer_use_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. - - `:computer_use` + - `class Logs` - - `:web_search_preview_2025_03_11` + Text output from the Code Interpreter tool call as part of a run step. - - `:image_generation` + - `logs: String` - - `:code_interpreter` + The text output from the Code Interpreter tool call. -### Beta Tool Search Tool + - `type: :logs` -- `class BetaToolSearchTool` + Always `logs`. - Hosted or BYOT tool search configuration for deferred tools. + - `:logs` - - `type: :tool_search` + - `class Image` - The type of the tool. Always `tool_search`. + - `image: Image{ file_id}` - - `:tool_search` + - `file_id: String` - - `description: String` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Description shown to the model for a client-executed tool search tool. + - `type: :image` - - `execution: :server | :client` + Always `image`. - Whether tool search is executed by the server or by the client. + - `:image` - - `:server` + - `type: :code_interpreter` - - `:client` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `parameters: untyped` + - `:code_interpreter` - Parameter schema for a client-executed tool search tool. + - `class FileSearchToolCall` -### Beta Web Search Preview Tool + - `id: String` -- `class BetaWebSearchPreviewTool` + The ID of the tool call object. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_search: FileSearch{ ranking_options, results}` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + For now, this is always going to be an empty object. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `ranking_options: RankingOptions{ ranker, score_threshold}` - - `:web_search_preview` + The ranking options for the file search. - - `:web_search_preview_2025_03_11` + - `ranker: :auto | :default_2024_08_21` - - `search_content_types: Array[:text | :image]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `:text` + - `:auto` - - `:image` + - `:default_2024_08_21` - - `search_context_size: :low | :medium | :high` + - `score_threshold: Float` - High 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 score threshold for the file search. All values must be a floating point number between 0 and 1. - - `:low` + - `results: Array[Result{ file_id, file_name, score, content}]` - - `:medium` + The results of the file search. - - `:high` + - `file_id: String` - - `user_location: UserLocation{ type, city, country, 2 more}` + The ID of the file that result was found in. - The user's location. + - `file_name: String` - - `type: :approximate` + The name of the file that result was found in. - The type of location approximation. Always `approximate`. + - `score: Float` - - `:approximate` + The score of the result. All values must be a floating point number between 0 and 1. - - `city: String` + - `content: Array[Content{ text, type}]` - Free text input for the city of the user, e.g. `San Francisco`. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `country: String` + - `text: String` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The text content of the file. - - `region: String` + - `type: :text` - Free text input for the region of the user, e.g. `California`. + The type of the content. - - `timezone: String` + - `:text` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: :file_search` -### Beta Web Search Tool + The type of tool call. This is always going to be `file_search` for this type of tool call. -- `class BetaWebSearchTool` + - `:file_search` - 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). + - `class FunctionToolCall` - - `type: :web_search | :web_search_2025_08_26` + - `id: String` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The ID of the tool call object. - - `:web_search` + - `function: Function{ arguments, name, output}` - - `:web_search_2025_08_26` + The definition of the function that was called. - - `filters: Filters{ allowed_domains}` + - `arguments: String` - Filters for the search. + The arguments passed to the function. - - `allowed_domains: Array[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. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `output: String` - - `search_context_size: :low | :medium | :high` + 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. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `type: :function` - - `:low` + The type of tool call. This is always going to be `function` for this type of tool call. - - `:medium` + - `:function` - - `:high` + - `type: :tool_calls` - - `user_location: UserLocation{ city, country, region, 2 more}` + Always `tool_calls`. - The approximate location of the user. + - `:tool_calls` - - `city: String` + - `thread_id: String` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `country: String` + - `type: :message_creation | :tool_calls` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `region: String` + - `:message_creation` - Free text input for the region of the user, e.g. `California`. + - `:tool_calls` - - `timezone: String` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `type: :approximate` + - `completion_tokens: Integer` - The type of location approximation. Always `approximate`. + Number of completion tokens used over the course of the run step. - - `:approximate` + - `prompt_tokens: Integer` -# Input Items + Number of prompt tokens used over the course of the run step. -## List input items + - `total_tokens: Integer` -`beta.responses.input_items.list(response_id, **kwargs) -> CursorPage` + Total number of tokens used (prompt + completion). -**get** `/responses/{response_id}/input_items?beta=true` + - `event: :"thread.run.step.created"` -List input items + - `:"thread.run.step.created"` -### Parameters + - `class ThreadRunStepInProgress` -- `response_id: String` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. -- `after: String` + - `data: RunStep` - An item ID to list items after, used in pagination. + Represents a step in execution of a run. -- `include: Array[BetaResponseIncludable]` + - `event: :"thread.run.step.in_progress"` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `:"thread.run.step.in_progress"` - - `:"file_search_call.results"` + - `class ThreadRunStepDelta` - - `:"web_search_call.results"` + Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - `:"web_search_call.action.sources"` + - `data: RunStepDeltaEvent` - - `:"message.input_image.image_url"` + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `:"computer_call_output.output.image_url"` + - `id: String` - - `:"code_interpreter_call.outputs"` + The identifier of the run step, which can be referenced in API endpoints. - - `:"reasoning.encrypted_content"` + - `delta: RunStepDelta` - - `:"message.output_text.logprobs"` + The delta containing the fields that have changed on the run step. -- `limit: Integer` + - `step_details: RunStepDeltaMessageDelta | ToolCallDeltaObject` - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + The details of the run step. -- `order: :asc | :desc` + - `class RunStepDeltaMessageDelta` - The order to return the input items in. Default is `desc`. + Details of the message creation by the run step. - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + - `type: :message_creation` - - `:asc` + Always `message_creation`. - - `:desc` + - `:message_creation` -- `betas: Array[:"responses_multi_agent=v1"]` + - `message_creation: MessageCreation{ message_id}` - - `:"responses_multi_agent=v1"` + - `message_id: String` -### Returns + The ID of the message that was created by this run step. -- `BetaResponseItem = BetaResponseInputMessageItem | BetaResponseOutputMessage | BetaResponseFileSearchToolCall | 29 more` + - `class ToolCallDeltaObject` - Content item used to generate a response. + Details of the tool call. - - `class BetaResponseInputMessageItem` + - `type: :tool_calls` - - `id: String` + Always `tool_calls`. - The unique ID of the message input. + - `:tool_calls` - - `content: BetaResponseInputMessageContentList` + - `tool_calls: Array[ToolCallDelta]` - A list of one or many input items to the model, containing different content - types. + 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`. - - `class BetaResponseInputText` + - `class CodeInterpreterToolCallDelta` - A text input to the model. + Details of the Code Interpreter tool call the run step was involved in. - - `text: String` + - `index: Integer` - The text input to the model. + The index of the tool call in the tool calls array. - - `type: :input_text` + - `type: :code_interpreter` - The type of the input item. Always `input_text`. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `:input_text` + - `:code_interpreter` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `id: String` + + The ID of the tool call. + + - `code_interpreter: CodeInterpreter{ input, 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. + The Code Interpreter tool call definition. - - `mode: :explicit` + - `input: String` - The breakpoint mode. Always `explicit`. + The input to the Code Interpreter tool call. - - `:explicit` + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - - `class BetaResponseInputImage` + 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class CodeInterpreterLogs` - - `detail: :low | :high | :auto | :original` + Text output from the Code Interpreter tool call as part of a run step. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `index: Integer` - - `:low` + The index of the output in the outputs array. - - `:high` + - `type: :logs` - - `:auto` + Always `logs`. - - `:original` + - `:logs` - - `type: :input_image` + - `logs: String` - The type of the input item. Always `input_image`. + The text output from the Code Interpreter tool call. - - `:input_image` + - `class CodeInterpreterOutputImage` - - `file_id: String` + - `index: Integer` - The ID of the file to be sent to the model. + The index of the output in the outputs array. - - `image_url: String` + - `type: :image` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Always `image`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:image` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `image: Image{ file_id}` - - `mode: :explicit` + - `file_id: String` - The breakpoint mode. Always `explicit`. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `:explicit` + - `class FileSearchToolCallDelta` - - `class BetaResponseInputFile` + - `file_search: untyped` - A file input to the model. + For now, this is always going to be an empty object. - - `type: :input_file` + - `index: Integer` - The type of the input item. Always `input_file`. + The index of the tool call in the tool calls array. - - `:input_file` + - `type: :file_search` - - `detail: :auto | :low | :high` + The type of tool call. This is always going to be `file_search` for this type of 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`. + - `:file_search` - - `:auto` + - `id: String` - - `:low` + The ID of the tool call object. - - `:high` + - `class FunctionToolCallDelta` - - `file_data: String` + - `index: Integer` - The content of the file to be sent to the model. + The index of the tool call in the tool calls array. - - `file_id: String` + - `type: :function` - The ID of the file to be sent to the model. + The type of tool call. This is always going to be `function` for this type of tool call. - - `file_url: String` + - `:function` - The URL of the file to be sent to the model. + - `id: String` - - `filename: String` + The ID of the tool call object. - The name of the file to be sent to the model. + - `function: Function{ arguments, name, output}` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The definition of the function that was called. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `arguments: String` - - `mode: :explicit` + The arguments passed to the function. - The breakpoint mode. Always `explicit`. + - `name: String` - - `:explicit` + The name of the function. - - `role: :user | :system | :developer` + - `output: String` - The role of the message input. One of `user`, `system`, or `developer`. + 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. - - `:user` + - `object: :"thread.run.step.delta"` - - `:system` + The object type, which is always `thread.run.step.delta`. - - `:developer` + - `:"thread.run.step.delta"` - - `type: :message` + - `event: :"thread.run.step.delta"` - The type of the message input. Always set to `message`. + - `:"thread.run.step.delta"` - - `:message` + - `class ThreadRunStepCompleted` - - `agent: Agent{ agent_name}` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - The agent that produced this item. + - `data: RunStep` - - `agent_name: String` + Represents a step in execution of a run. - The canonical name of the agent that produced this item. + - `event: :"thread.run.step.completed"` - - `status: :in_progress | :completed | :incomplete` + - `:"thread.run.step.completed"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class ThreadRunStepFailed` - - `:in_progress` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - - `:completed` + - `data: RunStep` - - `:incomplete` + Represents a step in execution of a run. - - `class BetaResponseOutputMessage` + - `event: :"thread.run.step.failed"` - An output message from the model. + - `:"thread.run.step.failed"` - - `id: String` + - `class ThreadRunStepCancelled` - The unique ID of the output message. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `data: RunStep` - The content of the output message. + Represents a step in execution of a run. - - `class BetaResponseOutputText` + - `event: :"thread.run.step.cancelled"` - A text output from the model. + - `:"thread.run.step.cancelled"` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `class ThreadRunStepExpired` - The annotations of the text output. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - - `class FileCitation` + - `data: RunStep` - A citation to a file. + Represents a step in execution of a run. - - `file_id: String` + - `event: :"thread.run.step.expired"` - The ID of the file. + - `:"thread.run.step.expired"` - - `filename: String` +### Run Stream Event - The filename of the file cited. +- `RunStreamEvent = ThreadRunCreated{ data, event} | ThreadRunQueued{ data, event} | ThreadRunInProgress{ data, event} | 7 more` - - `index: Integer` + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - The index of the file in the list of files. + - `class ThreadRunCreated` - - `type: :file_citation` + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - The type of the file citation. Always `file_citation`. + - `data: Run` - - `:file_citation` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class URLCitation` + - `id: String` - A citation for a web resource used to generate a model response. + The identifier, which can be referenced in API endpoints. - - `end_index: Integer` + - `assistant_id: String` - The index of the last character of the URL citation in the message. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `start_index: Integer` + - `cancelled_at: Integer` - The index of the first character of the URL citation in the message. + The Unix timestamp (in seconds) for when the run was cancelled. - - `title: String` + - `completed_at: Integer` - The title of the web resource. + The Unix timestamp (in seconds) for when the run was completed. - - `type: :url_citation` + - `created_at: Integer` - The type of the URL citation. Always `url_citation`. + The Unix timestamp (in seconds) for when the run was created. - - `:url_citation` + - `expires_at: Integer` - - `url: String` + The Unix timestamp (in seconds) for when the run will expire. - The URL of the web resource. + - `failed_at: Integer` - - `class ContainerFileCitation` + The Unix timestamp (in seconds) for when the run failed. - A citation for a container file used to generate a model response. + - `incomplete_details: IncompleteDetails{ reason}` - - `container_id: String` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The ID of the container file. + - `reason: :max_completion_tokens | :max_prompt_tokens` - - `end_index: Integer` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The index of the last character of the container file citation in the message. + - `:max_completion_tokens` - - `file_id: String` + - `:max_prompt_tokens` - The ID of the file. + - `instructions: String` - - `filename: String` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The filename of the container file cited. + - `last_error: LastError{ code, message}` - - `start_index: Integer` + The last error associated with this run. Will be `null` if there are no errors. - The index of the first character of the container file citation in the message. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - - `type: :container_file_citation` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The type of the container file citation. Always `container_file_citation`. + - `:server_error` - - `:container_file_citation` + - `:rate_limit_exceeded` - - `class FilePath` + - `:invalid_prompt` - A path to a file. + - `message: String` - - `file_id: String` + A human-readable description of the error. - The ID of the file. + - `max_completion_tokens: Integer` - - `index: Integer` + The maximum number of completion tokens specified to have been used over the course of the run. - The index of the file in the list of files. + - `max_prompt_tokens: Integer` - - `type: :file_path` + The maximum number of prompt tokens specified to have been used over the course of the run. - The type of the file path. Always `file_path`. + - `metadata: Metadata` - - `:file_path` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `text: String` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The text output from the model. + - `model: String` - - `type: :output_text` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the output text. Always `output_text`. + - `object: :"thread.run"` - - `:output_text` + The object type, which is always `thread.run`. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:"thread.run"` - - `token: String` + - `parallel_tool_calls: bool` - - `bytes: Array[Integer]` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `logprob: Float` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + Details on the action required to continue the run. Will be `null` if no action is required. - - `token: String` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - - `bytes: Array[Integer]` + Details on the tool outputs needed for this run to continue. - - `logprob: Float` + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `class BetaResponseOutputRefusal` + A list of the relevant tool calls. - A refusal from the model. + - `id: String` - - `refusal: 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 refusal explanation from the model. + - `function: Function{ arguments, name}` - - `type: :refusal` + The function definition. - The type of the refusal. Always `refusal`. + - `arguments: String` - - `:refusal` + The arguments that the model expects you to pass to the function. - - `role: :assistant` + - `name: String` - The role of the output message. Always `assistant`. + The name of the function. - - `:assistant` + - `type: :function` - - `status: :in_progress | :completed | :incomplete` + The type of tool call the output is required for. For now, this is always `function`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `:function` - - `:in_progress` + - `type: :submit_tool_outputs` - - `:completed` + For now, this is always `submit_tool_outputs`. - - `:incomplete` + - `:submit_tool_outputs` - - `type: :message` + - `response_format: AssistantResponseFormatOption` - The type of the output message. Always `message`. + 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`. - - `:message` + 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). - - `agent: Agent{ 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` + - `AssistantResponseFormatOption = :auto` - The canonical name of the agent that produced this item. + `auto` is the default value - - `phase: :commentary` + - `: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. + - `class ResponseFormatText` - - `:commentary` + Default response format. Used to generate text responses. - - `class BetaResponseFileSearchToolCall` + - `type: :text` - 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 type of response format being defined. Always `text`. - - `id: String` + - `:text` - The unique ID of the file search tool call. + - `class ResponseFormatJSONObject` - - `queries: Array[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 queries used to search for files. + - `type: :json_object` - - `status: :in_progress | :searching | :completed | 2 more` + The type of response format being defined. Always `json_object`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `:json_object` - - `:in_progress` + - `class ResponseFormatJSONSchema` - - `:searching` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:completed` + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `:incomplete` + Structured Outputs configuration options, including a JSON Schema. - - `:failed` + - `name: String` - - `type: :file_search_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 type of the file search tool call. Always `file_search_call`. + - `description: String` - - `:file_search_call` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `agent: Agent{ agent_name}` + - `schema: Hash[Symbol, untyped]` - 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: bool` - 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). - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `type: :json_schema` - The results of the file search tool call. + The type of response format being defined. Always `json_schema`. - - `attributes: Hash[Symbol, String | Float | bool]` + - `:json_schema` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `started_at: Integer` - - `String = String` + The Unix timestamp (in seconds) for when the run was started. - - `Float = Float` + - `status: RunStatus` - - `UnionMember2 = bool` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `file_id: String` + - `:queued` - The unique ID of the file. + - `:in_progress` - - `filename: String` + - `:requires_action` - The name of the file. + - `:cancelling` - - `score: Float` + - `:cancelled` - The relevance score of the file - a value between 0 and 1. + - `:failed` - - `text: String` + - `:completed` - The text that was retrieved from the file. + - `:incomplete` - - `class BetaResponseComputerToolCall` + - `:expired` - 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. + - `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 computer call. + - `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. - An identifier used when responding to the tool call with output. + - `Auto = :none | :auto | :required` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The pending safety checks for the computer call. + - `:none` - - `id: String` + - `:auto` - The ID of the pending safety check. + - `:required` - - `code: String` + - `class AssistantToolChoice` - The type of the pending safety check. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `message: String` + - `type: :function | :code_interpreter | :file_search` - Details about the pending safety check. + The type of the tool. If type is `function`, the function name must be set - - `status: :in_progress | :completed | :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: AssistantToolChoiceFunction` - - `:incomplete` + - `name: String` - - `type: :computer_call` + The name of the function to call. - The type of the computer call. Always `computer_call`. + - `tools: Array[AssistantTool]` - - `:computer_call` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `action: BetaComputerAction` + - `class CodeInterpreterTool` - A click action. + - `type: :code_interpreter` - - `class Click` + The type of tool being defined: `code_interpreter` - A click action. + - `:code_interpreter` - - `button: :left | :right | :wheel | 2 more` + - `class FileSearchTool` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: :file_search` - - `:left` + The type of tool being defined: `file_search` - - `:right` + - `:file_search` - - `:wheel` + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `:back` + Overrides for the file search tool. - - `:forward` + - `max_num_results: Integer` - - `type: :click` + 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. - Specifies the event type. For a click action, this property is always `click`. + 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. - - `:click` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `x: Integer` + 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 x-coordinate where the click occurred. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `y_: Integer` + - `score_threshold: Float` - The y-coordinate where the click occurred. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `keys: Array[String]` + - `ranker: :auto | :default_2024_08_21` - The keys being held while clicking. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class DoubleClick` + - `:auto` - A double click action. + - `:default_2024_08_21` - - `keys: Array[String]` + - `class FunctionTool` - The keys being held while double-clicking. + - `function: FunctionDefinition` - - `type: :double_click` + - `name: String` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `:double_click` + - `description: String` - - `x: Integer` + A description of what the function does, used by the model to choose when and how to call the function. - The x-coordinate where the double click occurred. + - `parameters: FunctionParameters` - - `y_: Integer` + 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 y-coordinate where the double click occurred. + Omitting `parameters` defines a function with an empty parameter list. - - `class Drag` + - `strict: bool` - A drag action. + 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). - - `path: Array[Path{ 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 tool being defined: `function` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `:function` - - `x: Integer` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - The x-coordinate. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `y_: Integer` + - `type: :auto | :last_messages` - The y-coordinate. + 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: :drag` + - `:auto` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `:last_messages` - - `:drag` + - `last_messages: Integer` - - `keys: Array[String]` + The number of most recent messages from the thread when constructing the context for the run. - The keys being held while dragging the mouse. + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - - `class Keypress` + 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 collection of keypresses the model would like to perform. + - `completion_tokens: Integer` - - `keys: Array[String]` + Number of completion tokens used over the course of the run. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `prompt_tokens: Integer` - - `type: :keypress` + Number of prompt tokens used over the course of the run. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `total_tokens: Integer` - - `:keypress` + Total number of tokens used (prompt + completion). - - `class Move` + - `temperature: Float` - A mouse move action. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: :move` + - `top_p: Float` - Specifies the event type. For a move action, this property is always set to `move`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `:move` + - `event: :"thread.run.created"` - - `x: Integer` + - `:"thread.run.created"` - The x-coordinate to move to. + - `class ThreadRunQueued` - - `y_: Integer` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - The y-coordinate to move to. + - `data: Run` - - `keys: Array[String]` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The keys being held while moving the mouse. + - `event: :"thread.run.queued"` - - `class Screenshot` + - `:"thread.run.queued"` - A screenshot action. + - `class ThreadRunInProgress` - - `type: :screenshot` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `data: Run` - - `:screenshot` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class Scroll` + - `event: :"thread.run.in_progress"` - A scroll action. + - `:"thread.run.in_progress"` - - `scroll_x: Integer` + - `class ThreadRunRequiresAction` - The horizontal scroll distance. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - `scroll_y: Integer` + - `data: Run` - The vertical scroll distance. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: :scroll` + - `event: :"thread.run.requires_action"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `:"thread.run.requires_action"` - - `:scroll` + - `class ThreadRunCompleted` - - `x: Integer` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - The x-coordinate where the scroll occurred. + - `data: Run` - - `y_: Integer` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The y-coordinate where the scroll occurred. + - `event: :"thread.run.completed"` - - `keys: Array[String]` + - `:"thread.run.completed"` - The keys being held while scrolling. + - `class ThreadRunIncomplete` - - `class Type` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - An action to type in text. + - `data: Run` - - `text: String` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The text to type. + - `event: :"thread.run.incomplete"` - - `type: :type` + - `:"thread.run.incomplete"` - Specifies the event type. For a type action, this property is always set to `type`. + - `class ThreadRunFailed` - - `:type` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - - `class Wait` + - `data: Run` - A wait action. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: :wait` + - `event: :"thread.run.failed"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `:"thread.run.failed"` - - `:wait` + - `class ThreadRunCancelling` - - `actions: BetaComputerActionList` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `data: Run` - - `class Click` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - A click action. + - `event: :"thread.run.cancelling"` - - `class DoubleClick` + - `:"thread.run.cancelling"` - A double click action. + - `class ThreadRunCancelled` - - `class Drag` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - A drag action. + - `data: Run` - - `class Keypress` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - A collection of keypresses the model would like to perform. + - `event: :"thread.run.cancelled"` - - `class Move` + - `:"thread.run.cancelled"` - A mouse move action. + - `class ThreadRunExpired` - - `class Screenshot` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - A screenshot action. + - `data: Run` - - `class Scroll` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - A scroll action. + - `event: :"thread.run.expired"` - - `class Type` + - `:"thread.run.expired"` - An action to type in text. +### Thread Stream Event - - `class Wait` +- `class ThreadStreamEvent` - A wait action. + Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - `agent: Agent{ agent_name}` + - `data: Thread` - The agent that produced this item. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `agent_name: String` + - `id: String` - The canonical name of the agent that produced this item. + The identifier, which can be referenced in API endpoints. - - `class BetaResponseComputerToolCallOutputItem` + - `created_at: Integer` - - `id: String` + The Unix timestamp (in seconds) for when the thread was created. - The unique ID of the computer call tool output. + - `metadata: Metadata` - - `call_id: String` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The ID of the computer tool call that produced the output. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `object: :thread` - A computer screenshot image used with the computer use tool. + The object type, which is always `thread`. - - `type: :computer_screenshot` + - `:thread` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `:computer_screenshot` + 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. - - `file_id: String` + - `code_interpreter: CodeInterpreter{ file_ids}` - The identifier of an uploaded file that contains the screenshot. + - `file_ids: Array[String]` - - `image_url: 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. - The URL of the screenshot image. + - `file_search: FileSearch{ vector_store_ids}` - - `status: :completed | :incomplete | :failed | :in_progress` + - `vector_store_ids: Array[String]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + 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. - - `:completed` + - `event: :"thread.created"` - - `:incomplete` + - `:"thread.created"` - - `:failed` + - `enabled: bool` - - `:in_progress` + Whether to enable input audio transcription. - - `type: :computer_call_output` +# Threads - The type of the computer tool call output. Always `computer_call_output`. +## Create thread - - `:computer_call_output` +`beta.threads.create(**kwargs) -> Thread` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` +**post** `/threads` - The safety checks reported by the API that have been acknowledged by the - developer. +Create a thread. - - `id: String` +### Parameters - The ID of the pending safety check. +- `messages: Array[Message{ content, role, attachments, metadata}]` - - `code: String` + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - The type of the pending safety check. + - `content: String | Array[MessageContentPartParam]` - - `message: String` + The text contents of the message. - Details about the pending safety check. + - `String = String` - - `agent: Agent{ agent_name}` + The text contents of the message. - The agent that produced this item. + - `ArrayOfContentParts = Array[MessageContentPartParam]` - - `agent_name: String` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). - The canonical name of the agent that produced this item. + - `class ImageFileContentBlock` - - `created_by: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The identifier of the actor that created the item. + - `image_file: ImageFile` - - `class BetaResponseFunctionWebSearch` + - `file_id: 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 [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. - - `id: String` + - `detail: :auto | :low | :high` - The unique ID of the web search 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`. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `: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). + - `:low` - - `class Search` + - `:high` - Action type "search" - Performs a web search query. + - `type: :image_file` - - `type: :search` + Always `image_file`. - The action type. + - `:image_file` - - `:search` + - `class ImageURLContentBlock` - - `queries: Array[String]` + References an image URL in the content of a message. - The search queries. + - `image_url: ImageURL` - - `query: String` + - `url: String` - The search query. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `sources: Array[Source{ type, url}]` + - `detail: :auto | :low | :high` - The sources used in the search. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: :url` + - `:auto` - The type of source. Always `url`. + - `:low` - - `:url` + - `:high` - - `url: String` + - `type: :image_url` - The URL of the source. + The type of the content part. - - `class OpenPage` + - `:image_url` - Action type "open_page" - Opens a specific URL from search results. + - `class TextContentBlockParam` - - `type: :open_page` + The text content that is part of a message. - The action type. + - `text: String` - - `:open_page` + Text content to be sent to the model - - `url: String` + - `type: :text` - The URL opened by the model. + Always `text`. - - `class FindInPage` + - `:text` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `role: :user | :assistant` - - `pattern: String` + The role of the entity that is creating the message. Allowed values include: - The pattern or text to search for within the page. + - `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: :find_in_page` + - `:user` - The action type. + - `:assistant` - - `:find_in_page` + - `attachments: Array[Attachment{ file_id, tools}]` - - `url: String` + A list of files attached to the message, and the tools they should be added to. - The URL of the page searched for the pattern. + - `file_id: String` - - `status: :in_progress | :searching | :completed | :failed` + The ID of the file to attach to the message. - The status of the web search tool call. + - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` - - `:in_progress` + The tools to add this file to. - - `:searching` + - `class CodeInterpreterTool` - - `:completed` + - `type: :code_interpreter` - - `:failed` + The type of tool being defined: `code_interpreter` - - `type: :web_search_call` + - `:code_interpreter` - The type of the web search tool call. Always `web_search_call`. + - `class FileSearch` - - `:web_search_call` + - `type: :file_search` - - `agent: Agent{ agent_name}` + The type of tool being defined: `file_search` - The agent that produced this item. + - `:file_search` - - `agent_name: String` + - `metadata: Metadata` - The canonical name of the agent that produced this 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. - - `class BetaResponseFunctionToolCallItem` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +- `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 function tool call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `status: :in_progress | :completed | :incomplete` +- `tool_resources: ToolResources{ code_interpreter, file_search}` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `:in_progress` + - `code_interpreter: CodeInterpreter{ file_ids}` - - `:completed` + - `file_ids: Array[String]` - - `:incomplete` + 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. - - `created_by: String` + - `file_search: FileSearch{ vector_store_ids, vector_stores}` - The identifier of the actor that created the item. + - `vector_store_ids: Array[String]` - - `class BetaResponseFunctionToolCallOutputItem` + 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. - - `id: String` + - `vector_stores: Array[VectorStore{ chunking_strategy, file_ids, metadata}]` - The unique ID of the function call tool output. + 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. - - `call_id: String` + - `chunking_strategy: Auto{ type} | Static{ static, type}` - The unique ID of the function tool call generated by the model. + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class Auto` - The output from the function call generated by your code. - Can be a string or an list of output content. + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - - `String = String` + - `type: :auto` - A string of the output of the function call. + Always `auto`. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `:auto` - Text, image, or file output of the function call. + - `class Static` - - `class BetaResponseInputText` + - `static: Static{ chunk_overlap_tokens, max_chunk_size_tokens}` - A text input to the model. + - `chunk_overlap_tokens: Integer` - - `class BetaResponseInputImage` + The number of tokens that overlap between chunks. The default value is `400`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `class BetaResponseInputFile` + - `max_chunk_size_tokens: Integer` - A file input to 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`. - - `status: :in_progress | :completed | :incomplete` + - `type: :static` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Always `static`. - - `:in_progress` + - `:static` - - `:completed` + - `file_ids: Array[String]` - - `:incomplete` + 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. - - `type: :function_call_output` + - `metadata: Metadata` - The type of the function tool call output. Always `function_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. - - `:function_call_output` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `agent: Agent{ agent_name}` +### Returns - The agent that produced this item. +- `class Thread` - - `agent_name: String` + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - The canonical name of the agent that produced this item. + - `id: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The identifier, which can be referenced in API endpoints. - The execution context that produced this tool call. + - `created_at: Integer` - - `class Direct` + The Unix timestamp (in seconds) for when the thread was created. - - `type: :direct` + - `metadata: Metadata` - The caller type. Always `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. - - `:direct` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class Program` + - `object: :thread` - - `caller_id: String` + The object type, which is always `thread`. - The call ID of the program item that produced this tool call. + - `:thread` - - `type: :program` + - `tool_resources: ToolResources{ code_interpreter, file_search}` - The caller type. Always `program`. + 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. - - `:program` + - `code_interpreter: CodeInterpreter{ file_ids}` - - `created_by: String` + - `file_ids: Array[String]` - The identifier of the actor that created the item. + 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. - - `class AgentMessage` + - `file_search: FileSearch{ vector_store_ids}` - - `id: String` + - `vector_store_ids: Array[String]` - The unique ID of the agent message. + 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. - - `author: String` +### Example - The sending agent identity. +```ruby +require "openai" - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` +openai = OpenAI::Client.new(api_key: "My API Key") - Encrypted content sent between agents. +thread = openai.beta.threads.create - - `class BetaResponseInputText` +puts(thread) +``` - A text input to the model. +#### Response - - `class BetaResponseOutputText` +```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 text output from the model. +## Create thread and run - - `class Text` +`beta.threads.create_and_run(**kwargs) -> Run` - A text content. +**post** `/threads/runs` - - `text: String` +Create a thread and run it in one request. - - `type: :text` +### Parameters - - `:text` +- `assistant_id: String` - - `class SummaryText` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - A summary text from the model. +- `instructions: String` - - `text: String` + Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. - A summary of the reasoning output from the model so far. +- `max_completion_tokens: Integer` - - `type: :summary_text` + 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 type of the object. Always `summary_text`. +- `max_prompt_tokens: Integer` - - `:summary_text` + 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. - - `class ReasoningText` +- `metadata: Metadata` - 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. - - `text: String` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The reasoning text from the model. +- `model: String | ChatModel` - - `type: :reasoning_text` + 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. - The type of the reasoning text. Always `reasoning_text`. + - `String = String` - - `:reasoning_text` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` - - `class BetaResponseOutputRefusal` + - `:"gpt-5.6-sol"` - A refusal from the model. + - `:"gpt-5.6-terra"` - - `class BetaResponseInputImage` + - `:"gpt-5.6-luna"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:"gpt-5.4"` - - `class ComputerScreenshot` + - `:"gpt-5.4-mini"` - A screenshot of a computer. + - `:"gpt-5.4-nano"` - - `detail: :low | :high | :auto | :original` + - `:"gpt-5.4-mini-2026-03-17"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:"gpt-5.4-nano-2026-03-17"` - - `:low` + - `:"gpt-5.3-chat-latest"` - - `:high` + - `:"gpt-5.2"` - - `:auto` + - `:"gpt-5.2-2025-12-11"` - - `:original` + - `:"gpt-5.2-chat-latest"` - - `file_id: String` + - `:"gpt-5.2-pro"` - The identifier of an uploaded file that contains the screenshot. + - `:"gpt-5.2-pro-2025-12-11"` - - `image_url: String` + - `:"gpt-5.1"` - The URL of the screenshot image. + - `:"gpt-5.1-2025-11-13"` - - `type: :computer_screenshot` + - `:"gpt-5.1-codex"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `:"gpt-5.1-mini"` - - `:computer_screenshot` + - `:"gpt-5.1-chat-latest"` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `:"gpt-5"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `:"gpt-5-mini"` - - `mode: :explicit` + - `:"gpt-5-nano"` - The breakpoint mode. Always `explicit`. + - `:"gpt-5-2025-08-07"` - - `:explicit` + - `:"gpt-5-mini-2025-08-07"` - - `class BetaResponseInputFile` + - `:"gpt-5-nano-2025-08-07"` - A file input to the model. + - `:"gpt-5-chat-latest"` - - `class EncryptedContent` + - `:"gpt-4.1"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `:"gpt-4.1-mini"` - - `encrypted_content: String` + - `:"gpt-4.1-nano"` - Opaque encrypted content. + - `:"gpt-4.1-2025-04-14"` - - `type: :encrypted_content` + - `:"gpt-4.1-mini-2025-04-14"` - The type of the input item. Always `encrypted_content`. + - `:"gpt-4.1-nano-2025-04-14"` - - `:encrypted_content` + - `:"o4-mini"` - - `recipient: String` + - `:"o4-mini-2025-04-16"` - The destination agent identity. + - `:o3` - - `type: :agent_message` + - `:"o3-2025-04-16"` - The type of the item. Always `agent_message`. + - `:"o3-mini"` - - `:agent_message` + - `:"o3-mini-2025-01-31"` - - `agent: Agent{ agent_name}` + - `:o1` - The agent that produced this item. + - `:"o1-2024-12-17"` - - `agent_name: String` + - `:"o1-preview"` - The canonical name of the agent that produced this item. + - `:"o1-preview-2024-09-12"` - - `class MultiAgentCall` + - `:"o1-mini"` - - `id: String` + - `:"o1-mini-2024-09-12"` - The unique ID of the multi-agent call item. + - `:"gpt-4o"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:"gpt-4o-2024-11-20"` - The multi-agent action to execute. + - `:"gpt-4o-2024-08-06"` - - `:spawn_agent` + - `:"gpt-4o-2024-05-13"` - - `:interrupt_agent` + - `:"gpt-4o-audio-preview"` - - `:list_agents` + - `:"gpt-4o-audio-preview-2024-10-01"` - - `:send_message` + - `:"gpt-4o-audio-preview-2024-12-17"` - - `:followup_task` + - `:"gpt-4o-audio-preview-2025-06-03"` - - `:wait_agent` + - `:"gpt-4o-mini-audio-preview"` - - `arguments: String` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - The JSON string of arguments generated for the action. + - `:"gpt-4o-search-preview"` - - `call_id: String` + - `:"gpt-4o-mini-search-preview"` - The unique ID linking this call to its output. + - `:"gpt-4o-search-preview-2025-03-11"` - - `type: :multi_agent_call` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - The type of the multi-agent call. Always `multi_agent_call`. + - `:"chatgpt-4o-latest"` - - `:multi_agent_call` + - `:"codex-mini-latest"` - - `agent: Agent{ agent_name}` + - `:"gpt-4o-mini"` - The agent that produced this item. + - `:"gpt-4o-mini-2024-07-18"` - - `agent_name: String` + - `:"gpt-4-turbo"` - The canonical name of the agent that produced this item. + - `:"gpt-4-turbo-2024-04-09"` - - `class MultiAgentCallOutput` + - `:"gpt-4-0125-preview"` - - `id: String` + - `:"gpt-4-turbo-preview"` - The unique ID of the multi-agent call output item. + - `:"gpt-4-1106-preview"` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `:"gpt-4-vision-preview"` - The multi-agent action that produced this result. + - `:"gpt-4"` - - `:spawn_agent` + - `:"gpt-4-0314"` - - `:interrupt_agent` + - `:"gpt-4-0613"` - - `:list_agents` + - `:"gpt-4-32k"` - - `:send_message` + - `:"gpt-4-32k-0314"` - - `:followup_task` + - `:"gpt-4-32k-0613"` - - `:wait_agent` + - `:"gpt-3.5-turbo"` - - `call_id: String` + - `:"gpt-3.5-turbo-16k"` - The unique ID of the multi-agent call. + - `:"gpt-3.5-turbo-0301"` - - `output: Array[BetaResponseOutputText]` + - `:"gpt-3.5-turbo-0613"` - Text output returned by the multi-agent action. + - `:"gpt-3.5-turbo-1106"` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `:"gpt-3.5-turbo-0125"` - The annotations of the text output. + - `:"gpt-3.5-turbo-16k-0613"` - - `text: String` +- `parallel_tool_calls: bool` - The text output from the model. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `type: :output_text` +- `response_format: AssistantResponseFormatOption` - The type of the output text. Always `output_text`. + 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`. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + 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: :multi_agent_call_output` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The type of the multi-agent result. Always `multi_agent_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. - - `:multi_agent_call_output` + - `AssistantResponseFormatOption = :auto` - - `agent: Agent{ agent_name}` + `auto` is the default value - The agent that produced this item. + - `:auto` - - `agent_name: String` + - `class ResponseFormatText` - The canonical name of the agent that produced this item. + Default response format. Used to generate text responses. - - `class BetaResponseToolSearchCall` + - `type: :text` - - `id: String` + The type of response format being defined. Always `text`. - The unique ID of the tool search call item. + - `:text` - - `arguments: untyped` + - `class ResponseFormatJSONObject` - Arguments used for the tool search call. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `call_id: String` + - `type: :json_object` - The unique ID of the tool search call generated by the model. + The type of response format being defined. Always `json_object`. - - `execution: :server | :client` + - `:json_object` - Whether tool search was executed by the server or by the client. + - `class ResponseFormatJSONSchema` - - `:server` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:client` + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `status: :in_progress | :completed | :incomplete` + Structured Outputs configuration options, including a JSON Schema. - The status of the tool search call item that was recorded. + - `name: String` - - `:in_progress` + 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. - - `:completed` + - `description: String` - - `:incomplete` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: :tool_search_call` + - `schema: Hash[Symbol, untyped]` - The type of the item. Always `tool_search_call`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:tool_search_call` + - `strict: bool` - - `agent: Agent{ 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` - - `created_by: String` +- `stream: bool` - The identifier of the actor that created the item. + 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. - - `class BetaResponseToolSearchOutputItem` +- `temperature: Float` - - `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. - The unique ID of the tool search output item. +- `thread: Thread{ messages, metadata, tool_resources}` - - `call_id: String` + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. - The unique ID of the tool search call generated by the model. + - `messages: Array[Message{ content, role, attachments, metadata}]` - - `execution: :server | :client` + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - Whether tool search was executed by the server or by the client. + - `content: String | Array[MessageContentPartParam]` - - `:server` + The text contents of the message. - - `:client` + - `String = String` - - `status: :in_progress | :completed | :incomplete` + The text contents of the message. - The status of the tool search output item that was recorded. + - `ArrayOfContentParts = Array[MessageContentPartParam]` - - `:in_progress` + 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). - - `:completed` + - `class ImageFileContentBlock` - - `:incomplete` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `tools: Array[BetaTool]` + - `image_file: ImageFile` - The loaded tool definitions returned by tool search. + - `file_id: String` - - `class BetaFunctionTool` + 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. - 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: :auto | :low | :high` - - `name: 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 name of the function to call. + - `:auto` - - `parameters: Hash[Symbol, untyped]` + - `:low` - A JSON schema object describing the parameters of the function. + - `:high` - - `strict: bool` + - `type: :image_file` - Whether strict parameter validation is enforced for this function tool. + Always `image_file`. - - `type: :function` + - `:image_file` - The type of the function tool. Always `function`. + - `class ImageURLContentBlock` - - `:function` + References an image URL in the content of a message. - - `allowed_callers: Array[:direct | :programmatic]` + - `image_url: ImageURL` - The tool invocation context(s). + - `url: String` - - `:direct` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `:programmatic` + - `detail: :auto | :low | :high` - - `defer_loading: bool` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - Whether this function is deferred and loaded via tool search. + - `:auto` - - `description: String` + - `:low` - A description of the function. Used by the model to determine whether or not to call the function. + - `:high` - - `output_schema: Hash[Symbol, untyped]` + - `type: :image_url` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The type of the content part. - - `class BetaFileSearchTool` + - `:image_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). + - `class TextContentBlockParam` - - `type: :file_search` + The text content that is part of a message. - The type of the file search tool. Always `file_search`. + - `text: String` - - `:file_search` + Text content to be sent to the model - - `vector_store_ids: Array[String]` + - `type: :text` - The IDs of the vector stores to search. + Always `text`. - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `:text` - A filter to apply. + - `role: :user | :assistant` - - `class ComparisonFilter` + The role of the entity that is creating the message. Allowed values include: - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `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. - - `key: String` + - `:user` - The key to compare against the value. + - `:assistant` - - `type: :eq | :ne | :gt | 5 more` + - `attachments: Array[Attachment{ file_id, tools}]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A list of files attached to the message, and the tools they should be added 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 + - `file_id: String` - - `:eq` + The ID of the file to attach to the message. - - `:ne` + - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` - - `:gt` + The tools to add this file to. - - `:gte` + - `class CodeInterpreterTool` - - `:lt` + - `type: :code_interpreter` - - `:lte` + The type of tool being defined: `code_interpreter` - - `:in` + - `:code_interpreter` - - `:nin` + - `class FileSearch` - - `value: String | Float | bool | Array[untyped]` + - `type: :file_search` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of tool being defined: `file_search` - - `String = String` + - `:file_search` - - `Float = Float` + - `metadata: Metadata` - - `UnionMember2 = bool` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `UnionMember3 = Array[untyped]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class CompoundFilter` + - `metadata: Metadata` - Combine multiple filters using `and` or `or`. + Set of 16 key-value pairs that can be attached to an object. 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: Array[ComparisonFilter{ key, type, value} | untyped]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `class ComparisonFilter` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `key: String` + - `file_ids: Array[String]` - The key to compare against the value. + 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: :eq | :ne | :gt | 5 more` + - `file_search: FileSearch{ vector_store_ids, vector_stores}` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `vector_store_ids: Array[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 [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. - - `:eq` + - `vector_stores: Array[VectorStore{ chunking_strategy, file_ids, metadata}]` - - `:ne` + 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. - - `:gt` + - `chunking_strategy: Auto{ type} | Static{ static, type}` - - `:gte` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `:lt` + - `class Auto` - - `:lte` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - - `:in` + - `type: :auto` - - `:nin` + Always `auto`. - - `value: String | Float | bool | Array[untyped]` + - `:auto` - The value to compare against the attribute key; supports string, number, or boolean types. + - `class Static` - - `String = String` + - `static: Static{ chunk_overlap_tokens, max_chunk_size_tokens}` - - `Float = Float` + - `chunk_overlap_tokens: Integer` - - `UnionMember2 = bool` + The number of tokens that overlap between chunks. The default value is `400`. - - `UnionMember3 = Array[untyped]` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `UnionMember1 = untyped` + - `max_chunk_size_tokens: Integer` - - `type: :and | :or` + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - Type of operation: `and` or `or`. + - `type: :static` - - `:and` + Always `static`. - - `:or` + - `:static` - - `max_num_results: Integer` + - `file_ids: Array[String]` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + 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. - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + - `metadata: Metadata` - Ranking options for 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. - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +- `tool_choice: AssistantToolChoiceOption` - - `embedding_weight: Float` + 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 weight of the embedding in the reciprocal ranking fusion. + - `Auto = :none | :auto | :required` - - `text_weight: Float` + `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 weight of the text in the reciprocal ranking fusion. + - `:none` - - `ranker: :auto | :"default-2024-11-15"` + - `:auto` - The ranker to use for the file search. + - `:required` - - `:auto` + - `class AssistantToolChoice` - - `:"default-2024-11-15"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `score_threshold: Float` + - `type: :function | :code_interpreter | :file_search` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The type of the tool. If type is `function`, the function name must be set - - `class BetaComputerTool` + - `:function` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:code_interpreter` - - `type: :computer` + - `:file_search` - The type of the computer tool. Always `computer`. + - `function: AssistantToolChoiceFunction` - - `:computer` + - `name: String` - - `class BetaComputerUsePreviewTool` + The name of the function to call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `tool_resources: ToolResources{ code_interpreter, file_search}` - - `display_height: Integer` + 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 height of the computer display. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `display_width: Integer` + - `file_ids: Array[String]` - The width of the computer display. + 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. - - `environment: :windows | :mac | :linux | 2 more` + - `file_search: FileSearch{ vector_store_ids}` - The type of computer environment to control. + - `vector_store_ids: Array[String]` - - `:windows` + 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. - - `:mac` +- `tools: Array[AssistantTool]` - - `:linux` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - - `:ubuntu` + - `class CodeInterpreterTool` - - `:browser` + - `class FileSearchTool` - - `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` - - `class BetaWebSearchTool` + - `file_search: FileSearch{ max_num_results, ranking_options}` - 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). + Overrides for the file search tool. - - `type: :web_search | :web_search_2025_08_26` + - `max_num_results: Integer` - 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: RankingOptions{ score_threshold, ranker}` - - `filters: Filters{ 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: Array[String]` + - `score_threshold: Float` - 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: :auto | :default_2024_08_21` - - `search_context_size: :low | :medium | :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` + - `class FunctionTool` - - `:high` + - `function: FunctionDefinition` - - `user_location: UserLocation{ 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: String` + - `description: 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: String` + - `parameters: 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: String` + Omitting `parameters` defines a function with an empty parameter list. - Free text input for the region of the user, e.g. `California`. + - `strict: bool` - - `timezone: 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: :approximate` + The type of tool being defined: `function` - The type of location approximation. Always `approximate`. + - `:function` - - `:approximate` +- `top_p: Float` - - `class Mcp` + 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](https://platform.openai.com/docs/guides/tools-remote-mcp). + We generally recommend altering this or temperature but not both. - - `server_label: String` +- `truncation_strategy: TruncationStrategy{ type, last_messages}` - A label for this MCP server, used to identify it in tool calls. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `type: :mcp` + - `type: :auto | :last_messages` - The type of the MCP tool. Always `mcp`. + 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`. - - `:mcp` + - `:auto` - - `allowed_callers: Array[:direct | :programmatic]` + - `:last_messages` - The tool invocation context(s). + - `last_messages: Integer` - - `:direct` + The number of most recent messages from the thread when constructing the context for the run. - - `:programmatic` +### Returns - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` +- `class Run` - List of allowed tool names or a filter object. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `McpAllowedTools = Array[String]` + - `id: String` - A string array of allowed tool names + The identifier, which can be referenced in API endpoints. - - `class McpToolFilter` + - `assistant_id: String` - A filter object to specify which tools are allowed. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `read_only: bool` + - `cancelled_at: Integer` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The Unix timestamp (in seconds) for when the run was cancelled. - - `tool_names: Array[String]` + - `completed_at: Integer` - List of allowed tool names. + The Unix timestamp (in seconds) for when the run was completed. - - `authorization: String` + - `created_at: Integer` - 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 Unix timestamp (in seconds) for when the run was created. - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `expires_at: Integer` - 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 Unix timestamp (in seconds) for when the run will expire. - Currently supported `connector_id` values are: + - `failed_at: Integer` - - 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 run failed. - - `:connector_dropbox` + - `incomplete_details: IncompleteDetails{ reason}` - - `:connector_gmail` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `:connector_googlecalendar` + - `reason: :max_completion_tokens | :max_prompt_tokens` - - `:connector_googledrive` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `:connector_microsoftteams` + - `:max_completion_tokens` - - `:connector_outlookcalendar` + - `:max_prompt_tokens` - - `:connector_outlookemail` + - `instructions: String` - - `:connector_sharepoint` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `defer_loading: bool` + - `last_error: LastError{ code, message}` - Whether this MCP tool is deferred and discovered via tool search. + The last error associated with this run. Will be `null` if there are no errors. - - `headers: Hash[Symbol, String]` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + - `:server_error` - Specify which of the MCP server's tools require approval. + - `:rate_limit_exceeded` - - `class McpToolApprovalFilter` + - `:invalid_prompt` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `message: String` - - `always: Always{ read_only, tool_names}` + A human-readable description of the error. - A filter object to specify which tools are allowed. + - `max_completion_tokens: Integer` - - `read_only: bool` + The maximum number of completion tokens specified to have been used over the course of the 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. + - `max_prompt_tokens: Integer` - - `tool_names: Array[String]` + The maximum number of prompt tokens specified to have been used over the course of the run. - List of allowed tool names. + - `metadata: Metadata` - - `never: Never{ read_only, tool_names}` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - A filter object to specify which tools are allowed. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `read_only: bool` + - `model: 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 model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `tool_names: Array[String]` + - `object: :"thread.run"` - List of allowed tool names. + The object type, which is always `thread.run`. - - `McpToolApprovalSetting = :always | :never` + - `:"thread.run"` - 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. + - `parallel_tool_calls: bool` - - `:always` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `:never` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - - `server_description: String` + Details on the action required to continue the run. Will be `null` if no action is required. - Optional description of the MCP server, used to provide more context. + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - - `server_url: String` + Details on the tool outputs needed for this run to continue. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `tunnel_id: String` + A list of the relevant tool calls. - 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` - - `class CodeInterpreter` + 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. - A tool that runs Python code to help generate a response to a prompt. + - `function: Function{ arguments, name}` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + The function definition. - 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 = String` + The arguments that the model expects you to pass to the function. - The container ID. + - `name: String` - - `class CodeInterpreterToolAuto` + The name of the function. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `type: :function` - - `type: :auto` + The type of tool call the output is required for. For now, this is always `function`. - Always `auto`. + - `:function` - - `:auto` + - `type: :submit_tool_outputs` - - `file_ids: Array[String]` + For now, this is always `submit_tool_outputs`. - An optional list of uploaded files to make available to your code. + - `:submit_tool_outputs` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `response_format: AssistantResponseFormatOption` - The memory limit for the code interpreter container. + 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`. - - `:"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](https://platform.openai.com/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"` + - `AssistantResponseFormatOption = :auto` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + `auto` is the default value - Network access policy for the container. + - `:auto` - - `class BetaContainerNetworkPolicyDisabled` + - `class ResponseFormatText` - - `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`. - - `class BetaContainerNetworkPolicyAllowlist` + - `:text` - - `allowed_domains: Array[String]` + - `class ResponseFormatJSONObject` - 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: Array[BetaContainerNetworkPolicyDomainSecret]` + - `class ResponseFormatJSONSchema` - Optional domain-scoped secrets for allowlisted domains. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `domain: String` + - `json_schema: JSONSchema{ 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: 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: Hash[Symbol, untyped]` - 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: bool` - - `allowed_callers: Array[:direct | :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](https://platform.openai.com/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` - - `class ProgrammaticToolCalling` + - `started_at: Integer` - - `type: :programmatic_tool_calling` + The Unix timestamp (in seconds) for when the run was started. - The type of the tool. Always `programmatic_tool_calling`. + - `status: RunStatus` - - `:programmatic_tool_calling` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `class ImageGeneration` + - `:queued` - A tool that generates images using the GPT image models. + - `:in_progress` - - `type: :image_generation` + - `:requires_action` - The type of the image generation tool. Always `image_generation`. + - `:cancelling` - - `:image_generation` + - `:cancelled` - - `action: :generate | :edit | :auto` + - `:failed` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `:completed` - - `:generate` + - `:incomplete` - - `:edit` + - `:expired` - - `:auto` + - `thread_id: String` - - `background: :transparent | :opaque | :auto` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this 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. + - `tool_choice: AssistantToolChoiceOption` - `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. + 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. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `Auto = :none | :auto | :required` - - `:transparent` + `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. - - `:opaque` + - `:none` - `:auto` - - `input_fidelity: :high | :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` + - `:required` - - `:low` + - `class AssistantToolChoice` - - `input_image_mask: InputImageMask{ file_id, image_url}` + Specifies a tool the model should use. Use to force the model to call a specific tool. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: :function | :code_interpreter | :file_search` - - `file_id: String` + The type of the tool. If type is `function`, the function name must be set - File ID for the mask image. + - `:function` - - `image_url: String` + - `:code_interpreter` - Base64-encoded mask image. + - `:file_search` - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `function: AssistantToolChoiceFunction` - The image generation model to use. Default: `gpt-image-1`. + - `name: String` - - `String = String` + The name of the function to call. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `tools: Array[AssistantTool]` - The image generation model to use. Default: `gpt-image-1`. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `:"gpt-image-1"` + - `class CodeInterpreterTool` - - `:"gpt-image-1-mini"` + - `type: :code_interpreter` - - `:"gpt-image-2"` + The type of tool being defined: `code_interpreter` - - `:"gpt-image-2-2026-04-21"` + - `:code_interpreter` - - `:"gpt-image-1.5"` + - `class FileSearchTool` - - `:"chatgpt-image-latest"` + - `type: :file_search` - - `moderation: :auto | :low` + The type of tool being defined: `file_search` - Moderation level for the generated image. Default: `auto`. + - `:file_search` - - `:auto` + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `:low` + Overrides for the file search tool. - - `output_compression: Integer` + - `max_num_results: Integer` - Compression level for the output image. Default: 100. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `output_format: :png | :webp | :jpeg` + 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 output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `:png` + 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. - - `:webp` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `:jpeg` + - `score_threshold: Float` - - `partial_images: Integer` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `ranker: :auto | :default_2024_08_21` - - `quality: :low | :medium | :high | :auto` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `:auto` - - `:low` + - `:default_2024_08_21` - - `:medium` + - `class FunctionTool` - - `:high` + - `function: FunctionDefinition` - - `:auto` + - `name: String` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :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. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `description: String` - - `String = String` + A description of what the function does, used by the model to choose when and how to call the function. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `parameters: FunctionParameters` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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 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. - - `:"1024x1024"` + Omitting `parameters` defines a function with an empty parameter list. - - `:"1024x1536"` + - `strict: bool` - - `:"1536x1024"` + 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). - - `:auto` + - `type: :function` - - `class LocalShell` + The type of tool being defined: `function` - A tool that allows the model to execute shell commands in a local environment. + - `:function` - - `type: :local_shell` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - The type of the local shell tool. Always `local_shell`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `:local_shell` + - `type: :auto | :last_messages` - - `class BetaFunctionShellTool` + 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. + - `:auto` - - `type: :shell` + - `:last_messages` - The type of the shell tool. Always `shell`. + - `last_messages: Integer` - - `:shell` + The number of most recent messages from the thread when constructing the context for the run. - - `allowed_callers: Array[:direct | :programmatic]` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - The tool invocation context(s). + 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.). - - `:direct` + - `completion_tokens: Integer` - - `:programmatic` + Number of completion tokens used over the course of the run. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `prompt_tokens: Integer` - - `class BetaContainerAuto` + Number of prompt tokens used over the course of the run. - - `type: :container_auto` + - `total_tokens: Integer` - Automatically creates a container for this request + Total number of tokens used (prompt + completion). - - `:container_auto` + - `temperature: Float` - - `file_ids: Array[String]` + The sampling temperature used for this run. If not set, defaults to 1. - An optional list of uploaded files to make available to your code. + - `top_p: Float` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + The nucleus sampling value used for this run. If not set, defaults to 1. - The memory limit for the container. +### Example - - `:"1g"` +```ruby +require "openai" - - `:"4g"` +openai = OpenAI::Client.new(api_key: "My API Key") - - `:"16g"` +run = openai.beta.threads.create_and_run(assistant_id: "assistant_id") - - `:"64g"` +puts(run) +``` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` +#### Response - Network access policy for the container. +```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 +} +``` - - `class BetaContainerNetworkPolicyDisabled` +## Retrieve thread - - `class BetaContainerNetworkPolicyAllowlist` +`beta.threads.retrieve(thread_id) -> Thread` - - `skills: Array[BetaSkillReference | BetaInlineSkill]` +**get** `/threads/{thread_id}` - An optional list of skills referenced by id or inline data. +Retrieves a thread. - - `class BetaSkillReference` +### Parameters - - `skill_id: String` +- `thread_id: String` - The ID of the referenced skill. +### Returns - - `type: :skill_reference` +- `class Thread` - References a skill created with the /v1/skills endpoint. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `:skill_reference` + - `id: String` - - `version: String` + The identifier, which can be referenced in API endpoints. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `created_at: Integer` - - `class BetaInlineSkill` + The Unix timestamp (in seconds) for when the thread was created. - - `description: String` + - `metadata: Metadata` - The description of the skill. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `name: String` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The name of the skill. + - `object: :thread` - - `source: BetaInlineSkillSource` + The object type, which is always `thread`. - Inline skill payload + - `:thread` - - `data: String` + - `tool_resources: ToolResources{ code_interpreter, file_search}` - Base64-encoded skill zip bundle. + 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. - - `media_type: :"application/zip"` + - `code_interpreter: CodeInterpreter{ file_ids}` - The media type of the inline skill payload. Must be `application/zip`. + - `file_ids: Array[String]` - - `:"application/zip"` + 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: :base64` + - `file_search: FileSearch{ vector_store_ids}` - The type of the inline skill source. Must be `base64`. + - `vector_store_ids: Array[String]` - - `:base64` + 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. - - `type: :inline` +### Example - Defines an inline skill for this request. +```ruby +require "openai" - - `:inline` +openai = OpenAI::Client.new(api_key: "My API Key") - - `class BetaLocalEnvironment` +thread = openai.beta.threads.retrieve("thread_id") - - `type: :local` +puts(thread) +``` - Use a local computer environment. +#### Response - - `:local` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `skills: Array[BetaLocalSkill]` +## Modify thread - An optional list of skills. +`beta.threads.update(thread_id, **kwargs) -> Thread` - - `description: String` +**post** `/threads/{thread_id}` - The description of the skill. +Modifies a thread. - - `name: String` +### Parameters - The name of the skill. +- `thread_id: String` - - `path: String` +- `metadata: Metadata` - The path to the directory containing the skill. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class BetaContainerReference` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `container_id: String` +- `tool_resources: ToolResources{ code_interpreter, file_search}` - The ID of the referenced container. + 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: :container_reference` + - `code_interpreter: CodeInterpreter{ file_ids}` - References a container created with the /v1/containers endpoint + - `file_ids: Array[String]` - - `:container_reference` + 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. - - `class BetaCustomTool` + - `file_search: FileSearch{ vector_store_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) + - `vector_store_ids: Array[String]` - - `name: 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 name of the custom tool, used to identify it in tool calls. +### Returns - - `type: :custom` +- `class Thread` - The type of the custom tool. Always `custom`. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `:custom` + - `id: String` - - `allowed_callers: Array[:direct | :programmatic]` + The identifier, which can be referenced in API endpoints. - The tool invocation context(s). + - `created_at: Integer` - - `:direct` + The Unix timestamp (in seconds) for when the thread was created. - - `:programmatic` + - `metadata: Metadata` - - `defer_loading: bool` + Set of 16 key-value pairs that can be attached to an object. 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 tool 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: String` + - `object: :thread` - Optional description of the custom tool, used to provide more context. + The object type, which is always `thread`. - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `:thread` - The input format for the custom tool. Default is unconstrained text. + - `tool_resources: ToolResources{ code_interpreter, file_search}` - - `class Text` + 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. - Unconstrained free-form text. + - `code_interpreter: CodeInterpreter{ file_ids}` - - `type: :text` + - `file_ids: Array[String]` - Unconstrained text format. Always `text`. + 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. - - `:text` + - `file_search: FileSearch{ vector_store_ids}` - - `class Grammar` + - `vector_store_ids: Array[String]` - A grammar defined by the user. + 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. - - `definition: String` +### Example - The grammar definition. +```ruby +require "openai" - - `syntax: :lark | :regex` +openai = OpenAI::Client.new(api_key: "My API Key") - The syntax of the grammar definition. One of `lark` or `regex`. +thread = openai.beta.threads.update("thread_id") - - `:lark` +puts(thread) +``` - - `:regex` +#### Response - - `type: :grammar` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - Grammar format. Always `grammar`. +## Delete thread - - `:grammar` +`beta.threads.delete(thread_id) -> ThreadDeleted` - - `class BetaNamespaceTool` +**delete** `/threads/{thread_id}` - Groups function/custom tools under a shared namespace. +Delete a thread. - - `description: String` +### Parameters - A description of the namespace shown to the model. +- `thread_id: String` - - `name: String` +### Returns - The namespace name used in tool calls (for example, `crm`). +- `class ThreadDeleted` - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `id: String` - The function/custom tools available inside this namespace. + - `deleted: bool` - - `class Function` + - `object: :"thread.deleted"` - - `name: String` + - `:"thread.deleted"` - - `type: :function` +### Example - - `:function` +```ruby +require "openai" - - `allowed_callers: Array[:direct | :programmatic]` +openai = OpenAI::Client.new(api_key: "My API Key") - The tool invocation context(s). +thread_deleted = openai.beta.threads.delete("thread_id") - - `:direct` +puts(thread_deleted) +``` - - `:programmatic` +#### Response - - `defer_loading: bool` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` - Whether this function should be deferred and discovered via tool search. +## Domain Types - - `description: String` +### Assistant Response Format Option - - `output_schema: Hash[Symbol, untyped]` +- `AssistantResponseFormatOption = :auto | ResponseFormatText | ResponseFormatJSONObject | ResponseFormatJSONSchema` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + 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`. - - `parameters: untyped` + 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). - - `strict: bool` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - 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. + **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. - - `class BetaCustomTool` + - `AssistantResponseFormatOption = :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) + `auto` is the default value - - `type: :namespace` + - `:auto` - The type of the tool. Always `namespace`. + - `class ResponseFormatText` - - `:namespace` + Default response format. Used to generate text responses. - - `class BetaToolSearchTool` + - `type: :text` - Hosted or BYOT tool search configuration for deferred tools. + The type of response format being defined. Always `text`. - - `type: :tool_search` + - `:text` - The type of the tool. Always `tool_search`. + - `class ResponseFormatJSONObject` - - `:tool_search` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `description: String` + - `type: :json_object` - Description shown to the model for a client-executed tool search tool. + The type of response format being defined. Always `json_object`. - - `execution: :server | :client` + - `:json_object` - Whether tool search is executed by the server or by the client. + - `class ResponseFormatJSONSchema` - - `:server` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:client` + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `parameters: untyped` + Structured Outputs configuration options, including a JSON Schema. - Parameter schema for a client-executed tool search tool. + - `name: String` - - `class BetaWebSearchPreviewTool` + 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. - 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). + - `description: String` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + 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 web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `schema: Hash[Symbol, untyped]` - - `:web_search_preview` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `:web_search_preview_2025_03_11` + - `strict: bool` - - `search_content_types: Array[:text | :image]` + 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` + - `type: :json_schema` - - `:image` + The type of response format being defined. Always `json_schema`. - - `search_context_size: :low | :medium | :high` + - `:json_schema` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. +### Assistant Tool Choice - - `:low` +- `class AssistantToolChoice` - - `:medium` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `:high` + - `type: :function | :code_interpreter | :file_search` - - `user_location: UserLocation{ type, city, country, 2 more}` + The type of the tool. If type is `function`, the function name must be set - The user's location. + - `:function` - - `type: :approximate` + - `:code_interpreter` - The type of location approximation. Always `approximate`. + - `:file_search` - - `:approximate` + - `function: AssistantToolChoiceFunction` - - `city: String` + - `name: String` - Free text input for the city of the user, e.g. `San Francisco`. + The name of the function to call. - - `country: String` +### Assistant Tool Choice Function - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. +- `class AssistantToolChoiceFunction` - - `region: String` + - `name: String` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `timezone: String` +### Assistant Tool Choice Option - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +- `AssistantToolChoiceOption = :none | :auto | :required | AssistantToolChoice` - - `class BetaApplyPatchTool` + 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. - Allows the assistant to create, delete, or update files using unified diffs. + - `Auto = :none | :auto | :required` - - `type: :apply_patch` + `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 type of the tool. Always `apply_patch`. + - `:none` - - `:apply_patch` + - `:auto` - - `allowed_callers: Array[:direct | :programmatic]` + - `:required` - The tool invocation context(s). + - `class AssistantToolChoice` - - `:direct` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `:programmatic` + - `type: :function | :code_interpreter | :file_search` - - `type: :tool_search_output` + The type of the tool. If type is `function`, the function name must be set - The type of the item. Always `tool_search_output`. + - `:function` - - `:tool_search_output` + - `:code_interpreter` - - `agent: Agent{ agent_name}` + - `:file_search` - The agent that produced this item. + - `function: AssistantToolChoiceFunction` - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the function to call. - - `created_by: String` +### Thread - The identifier of the actor that created the item. +- `class Thread` - - `class AdditionalTools` + Represents a thread that contains [messages](https://platform.openai.com/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 | :user | :assistant | 5 more` + - `created_at: Integer` - 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: ToolResources{ 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[BetaTool]` + - `code_interpreter: CodeInterpreter{ file_ids}` - The additional tool definitions made available at this item. + - `file_ids: Array[String]` - - `class BetaFunctionTool` + 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. - 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: FileSearch{ vector_store_ids}` - - `class BetaFileSearchTool` + - `vector_store_ids: Array[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 [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. - - `class BetaComputerTool` +### Thread Deleted - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `class ThreadDeleted` - - `class BetaComputerUsePreviewTool` + - `id: String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `deleted: bool` - - `class BetaWebSearchTool` + - `object: :"thread.deleted"` - 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). + - `:"thread.deleted"` - - `class Mcp` +# Runs - 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). +## List runs - - `class CodeInterpreter` +`beta.threads.runs.list(thread_id, **kwargs) -> CursorPage` - A tool that runs Python code to help generate a response to a prompt. +**get** `/threads/{thread_id}/runs` - - `class ProgrammaticToolCalling` +Returns a list of runs belonging to a thread. - - `class ImageGeneration` +### Parameters - A tool that generates images using the GPT image models. +- `thread_id: String` - - `class LocalShell` +- `after: String` - A tool that allows the model to execute shell commands in a local environment. + 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. - - `class BetaFunctionShellTool` +- `before: String` - A tool that allows the model to execute shell commands. + 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. - - `class BetaCustomTool` +- `limit: Integer` - 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 limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `class BetaNamespaceTool` +- `order: :asc | :desc` - Groups function/custom tools under a shared namespace. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `class BetaToolSearchTool` + - `:asc` - Hosted or BYOT tool search configuration for deferred tools. + - `:desc` - - `class BetaWebSearchPreviewTool` +### 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). +- `class Run` - - `class BetaApplyPatchTool` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - Allows the assistant to create, delete, or update files using unified diffs. + - `id: String` - - `type: :additional_tools` + The identifier, which can be referenced in API endpoints. - The type of the item. Always `additional_tools`. + - `assistant_id: String` - - `:additional_tools` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `agent: Agent{ agent_name}` + - `cancelled_at: Integer` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was cancelled. - - `agent_name: String` + - `completed_at: Integer` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was completed. - - `class BetaResponseReasoningItem` + - `created_at: Integer` - 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 Unix timestamp (in seconds) for when the run was created. - - `id: String` + - `expires_at: Integer` - The unique identifier of the reasoning content. + The Unix timestamp (in seconds) for when the run will expire. - - `summary: Array[Summary{ text, type}]` + - `failed_at: Integer` - Reasoning summary content. + The Unix timestamp (in seconds) for when the run failed. - - `text: String` + - `incomplete_details: IncompleteDetails{ reason}` - A summary of the reasoning output from the model so far. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `type: :summary_text` + - `reason: :max_completion_tokens | :max_prompt_tokens` - The type of the object. Always `summary_text`. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `:summary_text` + - `:max_completion_tokens` - - `type: :reasoning` + - `:max_prompt_tokens` - The type of the object. Always `reasoning`. + - `instructions: String` - - `:reasoning` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `agent: Agent{ agent_name}` + - `last_error: LastError{ code, message}` - The agent that produced this item. + The last error associated with this run. Will be `null` if there are no errors. - - `agent_name: String` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - The canonical name of the agent that produced this item. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `content: Array[Content{ text, type}]` + - `:server_error` - Reasoning text content. + - `:rate_limit_exceeded` - - `text: String` + - `:invalid_prompt` - The reasoning text from the model. + - `message: String` - - `type: :reasoning_text` + A human-readable description of the error. - The type of the reasoning text. Always `reasoning_text`. + - `max_completion_tokens: Integer` - - `:reasoning_text` + The maximum number of completion tokens specified to have been used over the course of the run. - - `encrypted_content: String` + - `max_prompt_tokens: Integer` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `status: :in_progress | :completed | :incomplete` + - `metadata: Metadata` - The status of the 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: String` - - `:incomplete` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `class Program` + - `object: :"thread.run"` - - `id: String` + The object type, which is always `thread.run`. - The unique ID of the program item. + - `:"thread.run"` - - `call_id: String` + - `parallel_tool_calls: bool` - The stable call ID of the program item. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `code: String` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - The JavaScript source executed by programmatic tool calling. + Details on the action required to continue the run. Will be `null` if no action is required. - - `fingerprint: String` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - Opaque program replay fingerprint that must be round-tripped. + Details on the tool outputs needed for this run to continue. - - `type: :program` + - `tool_calls: Array[RequiredActionFunctionToolCall]` - The type of the item. Always `program`. + A list of the relevant tool calls. - - `:program` + - `id: String` - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `function: Function{ arguments, name}` - - `agent_name: String` + The function definition. - The canonical name of the agent that produced this item. + - `arguments: String` - - `class ProgramOutput` + The arguments that the model expects you to pass to the function. - - `id: String` + - `name: String` - The unique ID of the program output item. + The name of the function. - - `call_id: String` + - `type: :function` - The call ID of the program item. + The type of tool call the output is required for. For now, this is always `function`. - - `result: String` + - `:function` - The result produced by the program item. + - `type: :submit_tool_outputs` - - `status: :completed | :incomplete` + For now, this is always `submit_tool_outputs`. - The terminal status of the program output item. + - `:submit_tool_outputs` - - `:completed` + - `response_format: AssistantResponseFormatOption` - - `:incomplete` + 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: :program_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](https://platform.openai.com/docs/guides/structured-outputs). - The type of the item. Always `program_output`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `:program_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: Agent{ agent_name}` + - `AssistantResponseFormatOption = :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. + - `class ResponseFormatText` - - `class BetaResponseCompactionItem` + Default response format. Used to generate text responses. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `type: :text` - - `id: String` + The type of response format being defined. Always `text`. - The unique ID of the compaction item. + - `:text` - - `encrypted_content: String` + - `class ResponseFormatJSONObject` - The encrypted content that was produced by compaction. + 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: :compaction` + - `type: :json_object` - The type of the item. Always `compaction`. + The type of response format being defined. Always `json_object`. - - `:compaction` + - `:json_object` - - `agent: Agent{ agent_name}` + - `class ResponseFormatJSONSchema` - 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` + - `json_schema: JSONSchema{ name, description, schema, strict}` - The canonical name of the agent that produced this item. + Structured Outputs configuration options, including a JSON Schema. - - `created_by: String` + - `name: String` - The identifier of the actor that created the 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. - - `class ImageGenerationCall` + - `description: String` - An image generation request made by the model. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `id: String` + - `schema: Hash[Symbol, untyped]` - The unique ID of the image generation call. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `result: String` + - `strict: bool` - The generated image encoded in base64. + 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). - - `status: :in_progress | :completed | :generating | :failed` + - `type: :json_schema` - The status of the image generation call. + The type of response format being defined. Always `json_schema`. - - `:in_progress` + - `:json_schema` - - `:completed` + - `started_at: Integer` - - `:generating` + The Unix timestamp (in seconds) for when the run was started. - - `:failed` + - `status: RunStatus` - - `type: :image_generation_call` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The type of the image generation call. Always `image_generation_call`. + - `:queued` - - `:image_generation_call` + - `:in_progress` - - `agent: Agent{ agent_name}` + - `:requires_action` - The agent that produced this item. + - `:cancelling` - - `agent_name: String` + - `:cancelled` - The canonical name of the agent that produced this item. + - `:failed` - - `class BetaResponseCodeInterpreterToolCall` + - `:completed` - A tool call to run code. + - `:incomplete` - - `id: String` + - `:expired` - The unique ID of the code interpreter tool call. + - `thread_id: String` - - `code: 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 code to run, or null if not available. + - `tool_choice: AssistantToolChoiceOption` - - `container_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 ID of the container used to run the code. + - `Auto = :none | :auto | :required` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + `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 outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `:none` - - `class Logs` + - `:auto` - The logs output from the code interpreter. + - `:required` - - `logs: String` + - `class AssistantToolChoice` - The logs output from the code interpreter. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `type: :logs` + - `type: :function | :code_interpreter | :file_search` - The type of the output. Always `logs`. + The type of the tool. If type is `function`, the function name must be set - - `:logs` + - `:function` - - `class Image` + - `:code_interpreter` - The image output from the code interpreter. + - `:file_search` - - `type: :image` + - `function: AssistantToolChoiceFunction` - The type of the output. Always `image`. + - `name: String` - - `:image` + The name of the function to call. - - `url: String` + - `tools: Array[AssistantTool]` - The URL of the image output from the code interpreter. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `class CodeInterpreterTool` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `type: :code_interpreter` - - `:in_progress` + The type of tool being defined: `code_interpreter` - - `:completed` + - `:code_interpreter` - - `:incomplete` + - `class FileSearchTool` - - `:interpreting` + - `type: :file_search` - - `:failed` + The type of tool being defined: `file_search` - - `type: :code_interpreter_call` + - `:file_search` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `:code_interpreter_call` + Overrides for the file search tool. - - `agent: Agent{ agent_name}` + - `max_num_results: Integer` - The agent that produced this item. + 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. - - `agent_name: 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 canonical name of the agent that produced this item. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `class LocalShellCall` + 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 tool call to run a command on the local shell. + 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: Float` - The unique ID of the local shell call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `action: Action{ command, env, type, 3 more}` + - `ranker: :auto | :default_2024_08_21` - Execute a shell command on the server. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `command: Array[String]` + - `:auto` - The command to run. + - `:default_2024_08_21` - - `env: Hash[Symbol, String]` + - `class FunctionTool` - Environment variables to set for the command. + - `function: FunctionDefinition` - - `type: :exec` + - `name: String` - The type of the local shell action. Always `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. - - `:exec` + - `description: String` - - `timeout_ms: Integer` + A description of what the function does, used by the model to choose when and how to call the function. - Optional timeout in milliseconds for the command. + - `parameters: FunctionParameters` - - `user: 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. - Optional user to run the command as. + Omitting `parameters` defines a function with an empty parameter list. - - `working_directory: String` + - `strict: bool` - Optional working directory to run the command in. + 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). - - `call_id: String` + - `type: :function` - The unique ID of the local shell tool call generated by the model. + The type of tool being defined: `function` + + - `:function` - - `status: :in_progress | :completed | :incomplete` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - The status of the local shell call. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `:in_progress` + - `type: :auto | :last_messages` - - `:completed` + 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`. - - `:incomplete` + - `:auto` - - `type: :local_shell_call` + - `:last_messages` - The type of the local shell call. Always `local_shell_call`. + - `last_messages: Integer` - - `:local_shell_call` + The number of most recent messages from the thread when constructing the context for the run. - - `agent: Agent{ agent_name}` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - 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.). - - `agent_name: String` + - `completion_tokens: Integer` - The canonical name of the agent that produced this item. + Number of completion tokens used over the course of the run. - - `class LocalShellCallOutput` + - `prompt_tokens: Integer` - The output of a local shell tool call. + Number of prompt tokens used over the course of the run. - - `id: String` + - `total_tokens: Integer` - The unique ID of the local shell tool call generated by the model. + Total number of tokens used (prompt + completion). - - `output: String` + - `temperature: Float` - A JSON string of the output of the local shell tool call. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: :local_shell_call_output` + - `top_p: Float` - The type of the local shell tool call output. Always `local_shell_call_output`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `:local_shell_call_output` +### Example - - `agent: Agent{ agent_name}` +```ruby +require "openai" - The agent that produced this item. +openai = OpenAI::Client.new(api_key: "My API Key") - - `agent_name: String` +page = openai.beta.threads.runs.list("thread_id") - The canonical name of the agent that produced this item. +puts(page) +``` - - `status: :in_progress | :completed | :incomplete` +#### Response - The status of the item. One of `in_progress`, `completed`, or `incomplete`. +```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" +} +``` - - `:in_progress` +## Create run - - `:completed` +`beta.threads.runs.create(thread_id, **kwargs) -> Run` - - `:incomplete` +**post** `/threads/{thread_id}/runs` - - `class BetaResponseFunctionShellToolCall` +Create a run. - A tool call that executes one or more shell commands in a managed environment. +### Parameters - - `id: String` +- `thread_id: String` - The unique ID of the shell tool call. Populated when this item is returned via API. +- `assistant_id: String` - - `action: Action{ commands, max_output_length, timeout_ms}` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - The shell commands and limits that describe how to run the tool call. +- `include: Array[RunStepInclude]` - - `commands: Array[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. - - `max_output_length: Integer` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Optional maximum number of characters to return from each command. + - `:"step_details.tool_calls[*].file_search.results[*].content"` - - `timeout_ms: Integer` +- `additional_instructions: String` - Optional timeout in milliseconds for the commands. + 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. - - `call_id: String` +- `additional_messages: Array[AdditionalMessage{ content, role, attachments, metadata}]` - The unique ID of the shell tool call generated by the model. + Adds additional messages to the thread before creating the run. - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `content: String | Array[MessageContentPartParam]` - Represents the use of a local environment to perform shell actions. + The text contents of the message. - - `class BetaResponseLocalEnvironment` + - `String = String` - Represents the use of a local environment to perform shell actions. + The text contents of the message. - - `type: :local` + - `ArrayOfContentParts = Array[MessageContentPartParam]` - The environment type. Always `local`. + 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). - - `:local` + - `class ImageFileContentBlock` - - `class BetaResponseContainerReference` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Represents a container created with /v1/containers. + - `image_file: ImageFile` - - `container_id: String` + - `file_id: String` - - `type: :container_reference` + 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 environment type. Always `container_reference`. + - `detail: :auto | :low | :high` - - `:container_reference` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `status: :in_progress | :completed | :incomplete` + - `:auto` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `:low` - - `:in_progress` + - `:high` - - `:completed` + - `type: :image_file` - - `:incomplete` + Always `image_file`. - - `type: :shell_call` + - `:image_file` - The type of the item. Always `shell_call`. + - `class ImageURLContentBlock` - - `:shell_call` + References an image URL in the content of a message. - - `agent: Agent{ agent_name}` + - `image_url: ImageURL` - The agent that produced this item. + - `url: String` - - `agent_name: String` + The external 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. + - `detail: :auto | :low | :high` - - `caller_: Direct{ type} | Program{ caller_id, type}` + 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 execution context that produced this tool call. + - `:auto` - - `class Direct` + - `:low` - - `type: :direct` + - `:high` - - `:direct` + - `type: :image_url` - - `class Program` + The type of the content part. - - `caller_id: String` + - `:image_url` - The call ID of the program item that produced this tool call. + - `class TextContentBlockParam` - - `type: :program` + The text content that is part of a message. - - `:program` + - `text: String` - - `created_by: String` + Text content to be sent to the model - The ID of the entity that created this tool call. + - `type: :text` - - `class BetaResponseFunctionShellToolCallOutput` + Always `text`. - The output of a shell tool call that was emitted. + - `:text` - - `id: String` + - `role: :user | :assistant` - The unique ID of the shell call output. Populated when this item is returned via API. + The role of the entity that is creating the message. Allowed values include: - - `call_id: String` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - The unique ID of the shell tool call generated by the model. + - `:user` - - `max_output_length: Integer` + - `:assistant` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `attachments: Array[Attachment{ file_id, tools}]` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + A list of files attached to the message, and the tools they should be added to. - An array of shell call output contents + - `file_id: String` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + The ID of the file to attach to the message. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` - - `class Timeout` + The tools to add this file to. - Indicates that the shell call exceeded its configured time limit. + - `class CodeInterpreterTool` - - `type: :timeout` + - `type: :code_interpreter` - The outcome type. Always `timeout`. + The type of tool being defined: `code_interpreter` - - `:timeout` + - `:code_interpreter` - - `class Exit` + - `class FileSearch` - Indicates that the shell commands finished and returned an exit code. + - `type: :file_search` - - `exit_code: Integer` + The type of tool being defined: `file_search` - Exit code from the shell process. + - `:file_search` - - `type: :exit` + - `metadata: Metadata` - The outcome type. Always `exit`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `:exit` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `stderr: String` +- `instructions: String` - The standard error output that was captured. + 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. - - `stdout: String` +- `max_completion_tokens: Integer` - The standard output that was captured. + 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. - - `created_by: String` +- `max_prompt_tokens: Integer` - The identifier of the actor that created the item. + 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. - - `status: :in_progress | :completed | :incomplete` +- `metadata: Metadata` - The status of the shell call output. One of `in_progress`, `completed`, or `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. - - `:in_progress` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `:completed` +- `model: String | ChatModel` - - `:incomplete` + 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. - - `type: :shell_call_output` + - `String = String` - The type of the shell call output. Always `shell_call_output`. + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` - - `:shell_call_output` + - `:"gpt-5.6-sol"` - - `agent: Agent{ agent_name}` + - `:"gpt-5.6-terra"` - The agent that produced this item. + - `:"gpt-5.6-luna"` - - `agent_name: String` + - `:"gpt-5.4"` - The canonical name of the agent that produced this item. + - `:"gpt-5.4-mini"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-5.4-nano"` - The execution context that produced this tool call. + - `:"gpt-5.4-mini-2026-03-17"` - - `class Direct` + - `:"gpt-5.4-nano-2026-03-17"` - - `type: :direct` + - `:"gpt-5.3-chat-latest"` - - `:direct` + - `:"gpt-5.2"` - - `class Program` + - `:"gpt-5.2-2025-12-11"` - - `caller_id: String` + - `:"gpt-5.2-chat-latest"` - The call ID of the program item that produced this tool call. + - `:"gpt-5.2-pro"` - - `type: :program` + - `:"gpt-5.2-pro-2025-12-11"` - - `:program` + - `:"gpt-5.1"` - - `created_by: String` + - `:"gpt-5.1-2025-11-13"` - The identifier of the actor that created the item. + - `:"gpt-5.1-codex"` - - `class BetaResponseApplyPatchToolCall` + - `:"gpt-5.1-mini"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `:"gpt-5.1-chat-latest"` - - `id: String` + - `:"gpt-5"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `:"gpt-5-mini"` - - `call_id: String` + - `:"gpt-5-nano"` - The unique ID of the apply patch tool call generated by the model. + - `:"gpt-5-2025-08-07"` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `:"gpt-5-mini-2025-08-07"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `:"gpt-5-nano-2025-08-07"` - - `class CreateFile` + - `:"gpt-5-chat-latest"` - Instruction describing how to create a file via the apply_patch tool. + - `:"gpt-4.1"` - - `diff: String` + - `:"gpt-4.1-mini"` - Diff to apply. + - `:"gpt-4.1-nano"` - - `path: String` + - `:"gpt-4.1-2025-04-14"` - Path of the file to create. + - `:"gpt-4.1-mini-2025-04-14"` - - `type: :create_file` + - `:"gpt-4.1-nano-2025-04-14"` - Create a new file with the provided diff. + - `:"o4-mini"` - - `:create_file` + - `:"o4-mini-2025-04-16"` - - `class DeleteFile` + - `:o3` - Instruction describing how to delete a file via the apply_patch tool. + - `:"o3-2025-04-16"` - - `path: String` + - `:"o3-mini"` - Path of the file to delete. + - `:"o3-mini-2025-01-31"` - - `type: :delete_file` + - `:o1` - Delete the specified file. + - `:"o1-2024-12-17"` - - `:delete_file` + - `:"o1-preview"` - - `class UpdateFile` + - `:"o1-preview-2024-09-12"` - Instruction describing how to update a file via the apply_patch tool. + - `:"o1-mini"` - - `diff: String` + - `:"o1-mini-2024-09-12"` - Diff to apply. + - `:"gpt-4o"` - - `path: String` + - `:"gpt-4o-2024-11-20"` - Path of the file to update. + - `:"gpt-4o-2024-08-06"` - - `type: :update_file` + - `:"gpt-4o-2024-05-13"` - Update an existing file with the provided diff. + - `:"gpt-4o-audio-preview"` - - `:update_file` + - `:"gpt-4o-audio-preview-2024-10-01"` - - `status: :in_progress | :completed` + - `:"gpt-4o-audio-preview-2024-12-17"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `:"gpt-4o-audio-preview-2025-06-03"` - - `:in_progress` + - `:"gpt-4o-mini-audio-preview"` - - `:completed` + - `:"gpt-4o-mini-audio-preview-2024-12-17"` - - `type: :apply_patch_call` + - `:"gpt-4o-search-preview"` - The type of the item. Always `apply_patch_call`. + - `:"gpt-4o-mini-search-preview"` - - `:apply_patch_call` + - `:"gpt-4o-search-preview-2025-03-11"` - - `agent: Agent{ agent_name}` + - `:"gpt-4o-mini-search-preview-2025-03-11"` - The agent that produced this item. + - `:"chatgpt-4o-latest"` - - `agent_name: String` + - `:"codex-mini-latest"` - The canonical name of the agent that produced this item. + - `:"gpt-4o-mini"` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:"gpt-4o-mini-2024-07-18"` - The execution context that produced this tool call. + - `:"gpt-4-turbo"` - - `class Direct` + - `:"gpt-4-turbo-2024-04-09"` - - `type: :direct` + - `:"gpt-4-0125-preview"` - - `:direct` + - `:"gpt-4-turbo-preview"` - - `class Program` + - `:"gpt-4-1106-preview"` - - `caller_id: String` + - `:"gpt-4-vision-preview"` - The call ID of the program item that produced this tool call. + - `:"gpt-4"` - - `type: :program` + - `:"gpt-4-0314"` - - `:program` + - `:"gpt-4-0613"` - - `created_by: String` + - `:"gpt-4-32k"` - The ID of the entity that created this tool call. + - `:"gpt-4-32k-0314"` - - `class BetaResponseApplyPatchToolCallOutput` + - `:"gpt-4-32k-0613"` - The output emitted by an apply patch tool call. + - `:"gpt-3.5-turbo"` - - `id: String` + - `:"gpt-3.5-turbo-16k"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:"gpt-3.5-turbo-0301"` - - `call_id: String` + - `:"gpt-3.5-turbo-0613"` - The unique ID of the apply patch tool call generated by the model. + - `:"gpt-3.5-turbo-1106"` - - `status: :completed | :failed` + - `:"gpt-3.5-turbo-0125"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `:"gpt-3.5-turbo-16k-0613"` - - `:completed` +- `parallel_tool_calls: bool` - - `:failed` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `type: :apply_patch_call_output` +- `reasoning_effort: ReasoningEffort` - The type of the item. Always `apply_patch_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. - - `:apply_patch_call_output` + - `:none` - - `agent: Agent{ agent_name}` + - `:minimal` - The agent that produced this item. + - `:low` - - `agent_name: String` + - `:medium` - The canonical name of the agent that produced this item. + - `:high` - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:xhigh` - The execution context that produced this tool call. + - `:max` - - `class Direct` +- `response_format: AssistantResponseFormatOption` - - `type: :direct` + 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` + 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). - - `class Program` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `caller_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 call ID of the program item that produced this tool call. + - `AssistantResponseFormatOption = :auto` - - `type: :program` + `auto` is the default value - - `:program` + - `:auto` - - `created_by: String` + - `class ResponseFormatText` - The ID of the entity that created this tool call output. + Default response format. Used to generate text responses. - - `output: String` + - `type: :text` - Optional textual output returned by the apply patch tool. + The type of response format being defined. Always `text`. - - `class McpListTools` + - `:text` - A list of tools available on an MCP server. + - `class ResponseFormatJSONObject` - - `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 unique ID of the list. + - `type: :json_object` - - `server_label: String` + The type of response format being defined. Always `json_object`. - The label of the MCP server. + - `:json_object` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + - `class ResponseFormatJSONSchema` - The tools available on the server. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `input_schema: untyped` + - `json_schema: JSONSchema{ name, description, schema, strict}` - The JSON schema describing the tool's input. + Structured Outputs configuration options, including a JSON Schema. - `name: String` - The name of the tool. + 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. - - `annotations: untyped` + - `description: String` - Additional annotations about the tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `description: String` + - `schema: Hash[Symbol, untyped]` - The description of the tool. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: :mcp_list_tools` + - `strict: bool` - The type of the item. Always `mcp_list_tools`. + 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). - - `:mcp_list_tools` + - `type: :json_schema` - - `agent: Agent{ agent_name}` + The type of response format being defined. Always `json_schema`. - The agent that produced this item. + - `:json_schema` - - `agent_name: String` +- `stream: bool` - The canonical name of the agent that produced this item. + 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. - - `error: String` +- `temperature: Float` - Error message if the server could not list tools. + 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. - - `class McpApprovalRequest` +- `tool_choice: AssistantToolChoiceOption` - A request for human approval of a tool invocation. + 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` + - `Auto = :none | :auto | :required` - The unique ID of the approval request. + `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. - - `arguments: String` + - `:none` - A JSON string of arguments for the tool. + - `:auto` - - `name: String` + - `:required` - The name of the tool to run. + - `class AssistantToolChoice` - - `server_label: String` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The label of the MCP server making the request. + - `type: :function | :code_interpreter | :file_search` - - `type: :mcp_approval_request` + The type of the tool. If type is `function`, the function name must be set - The type of the item. Always `mcp_approval_request`. + - `:function` - - `:mcp_approval_request` + - `:code_interpreter` - - `agent: Agent{ agent_name}` + - `:file_search` - The agent that produced this item. + - `function: AssistantToolChoiceFunction` - - `agent_name: String` + - `name: String` - The canonical name of the agent that produced this item. + The name of the function to call. - - `class McpApprovalResponse` +- `tools: Array[AssistantTool]` - A response to an MCP approval request. + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - - `id: String` + - `class CodeInterpreterTool` - The unique ID of the approval response + - `class FileSearchTool` - - `approval_request_id: String` + - `type: :file_search` - The ID of the approval request being answered. + The type of tool being defined: `file_search` - - `approve: bool` + - `:file_search` - Whether the request was approved. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `type: :mcp_approval_response` + Overrides for the file search tool. - The type of the item. Always `mcp_approval_response`. + - `max_num_results: Integer` - - `:mcp_approval_response` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `agent_name: 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 canonical name of 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. - - `reason: String` + - `score_threshold: Float` - Optional reason for the decision. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `class McpCall` + - `ranker: :auto | :default_2024_08_21` - An invocation of a tool on an MCP server. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `id: String` + - `:auto` - The unique ID of the tool call. + - `:default_2024_08_21` - - `arguments: String` + - `class FunctionTool` - A JSON string of the arguments passed to the tool. + - `function: FunctionDefinition` - `name: String` - The name of the tool that was run. + 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. - - `server_label: String` + - `description: String` - The label of the MCP server running the tool. + A description of what the function does, used by the model to choose when and how to call the function. - - `type: :mcp_call` + - `parameters: FunctionParameters` - The type of the item. Always `mcp_call`. + 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. - - `:mcp_call` + Omitting `parameters` defines a function with an empty parameter list. - - `agent: Agent{ agent_name}` + - `strict: bool` - 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` - - `approval_request_id: String` + - `: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. +- `top_p: Float` - - `error: 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 error from the tool call, if any. + We generally recommend altering this or temperature but not both. - - `output: String` +- `truncation_strategy: TruncationStrategy{ type, last_messages}` - The output from the tool call. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `type: :auto | :last_messages` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + 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`. - - `:in_progress` + - `:auto` - - `:completed` + - `:last_messages` - - `:incomplete` + - `last_messages: Integer` - - `:calling` + The number of most recent messages from the thread when constructing the context for the run. - - `:failed` +### Returns - - `class BetaResponseCustomToolCallItem` +- `class Run` - A call to a custom tool created by the model. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - `id: String` - The unique ID of the custom tool call item. + The identifier, which can be referenced in API endpoints. - - `status: :in_progress | :completed | :incomplete` + - `assistant_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 [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `:in_progress` + - `cancelled_at: Integer` - - `:completed` + The Unix timestamp (in seconds) for when the run was cancelled. - - `:incomplete` + - `completed_at: Integer` - - `created_by: String` + The Unix timestamp (in seconds) for when the run was completed. - The identifier of the actor that created the item. + - `created_at: Integer` - - `class BetaResponseCustomToolCallOutputItem` + The Unix timestamp (in seconds) for when the run was created. - The output of a custom tool call from your code, being sent back to the model. + - `expires_at: Integer` - - `id: String` + The Unix timestamp (in seconds) for when the run will expire. - The unique ID of the custom tool call output item. + - `failed_at: Integer` - - `status: :in_progress | :completed | :incomplete` + The Unix timestamp (in seconds) for when the run failed. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `incomplete_details: IncompleteDetails{ reason}` - - `:in_progress` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `:completed` + - `reason: :max_completion_tokens | :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. - - `created_by: String` + - `:max_completion_tokens` - The identifier of the actor that created the item. + - `:max_prompt_tokens` -### Example + - `instructions: String` -```ruby -require "openai" + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. -openai = OpenAI::Client.new(api_key: "My API Key") + - `last_error: LastError{ code, message}` -page = openai.beta.responses.input_items.list("response_id") + The last error associated with this run. Will be `null` if there are no errors. -puts(page) -``` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` -#### Response + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. -```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" -} -``` + - `:server_error` -## Domain Types + - `:rate_limit_exceeded` -### Beta Response Item List + - `:invalid_prompt` -- `class BetaResponseItemList` + - `message: String` - A list of Response items. + A human-readable description of the error. - - `data: Array[BetaResponseItem]` + - `max_completion_tokens: Integer` - A list of items used to generate this response. + The maximum number of completion tokens specified to have been used over the course of the run. - - `class BetaResponseInputMessageItem` + - `max_prompt_tokens: Integer` - - `id: String` + The maximum number of prompt tokens specified to have been used over the course of the run. - The unique ID of the message input. + - `metadata: Metadata` - - `content: BetaResponseInputMessageContentList` + Set of 16 key-value pairs that can be attached to an object. 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 list of one or many input items to the model, containing different content - types. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class BetaResponseInputText` + - `model: String` - A text input to the model. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `text: String` + - `object: :"thread.run"` - The text input to the model. + The object type, which is always `thread.run`. - - `type: :input_text` + - `:"thread.run"` - The type of the input item. Always `input_text`. + - `parallel_tool_calls: bool` - - `:input_text` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `required_action: RequiredAction{ submit_tool_outputs, 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. + Details on the action required to continue the run. Will be `null` if no action is required. - - `mode: :explicit` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - The breakpoint mode. Always `explicit`. + Details on the tool outputs needed for this run to continue. - - `:explicit` + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `class BetaResponseInputImage` + A list of the relevant tool calls. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `id: String` - - `detail: :low | :high | :auto | :original` + 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 detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `function: Function{ arguments, name}` - - `:low` + The function definition. - - `:high` + - `arguments: String` - - `:auto` + The arguments that the model expects you to pass to the function. - - `:original` + - `name: String` - - `type: :input_image` + The name of the function. - The type of the input item. Always `input_image`. + - `type: :function` - - `:input_image` + The type of tool call the output is required for. For now, this is always `function`. - - `file_id: String` + - `:function` - The ID of the file to be sent to the model. + - `type: :submit_tool_outputs` - - `image_url: String` + For now, this is always `submit_tool_outputs`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `:submit_tool_outputs` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `response_format: AssistantResponseFormatOption` - Marks the exact end of a reusable 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 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`. - - `mode: :explicit` + 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 breakpoint mode. Always `explicit`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `:explicit` + **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. - - `class BetaResponseInputFile` + - `AssistantResponseFormatOption = :auto` - A file input to the model. + `auto` is the default value - - `type: :input_file` + - `:auto` - The type of the input item. Always `input_file`. + - `class ResponseFormatText` - - `:input_file` + Default response format. Used to generate text responses. - - `detail: :auto | :low | :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`. + The type of response format being defined. Always `text`. - - `:auto` + - `:text` - - `:low` + - `class ResponseFormatJSONObject` - - `:high` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `file_data: String` + - `type: :json_object` - The content of the file to be sent to the model. + The type of response format being defined. Always `json_object`. - - `file_id: String` + - `:json_object` - The ID of the file to be sent to the model. + - `class ResponseFormatJSONSchema` - - `file_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 file to be sent to the model. + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `filename: String` + Structured Outputs configuration options, including a JSON Schema. - The name of the file to be sent to the model. + - `name: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + 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. - Marks the exact end of a reusable 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: String` - - `mode: :explicit` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The breakpoint mode. Always `explicit`. + - `schema: Hash[Symbol, untyped]` - - `:explicit` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `role: :user | :system | :developer` + - `strict: bool` - The role of the message input. One of `user`, `system`, or `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](https://platform.openai.com/docs/guides/structured-outputs). - - `:user` + - `type: :json_schema` - - `:system` + The type of response format being defined. Always `json_schema`. - - `:developer` + - `:json_schema` - - `type: :message` + - `started_at: Integer` - The type of the message input. Always set to `message`. + The Unix timestamp (in seconds) for when the run was started. - - `:message` + - `status: RunStatus` - - `agent: Agent{ 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: :in_progress | :completed | :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` - - `class BetaResponseOutputMessage` + - `:expired` - An output message from the model. + - `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 output message. + - `tool_choice: AssistantToolChoiceOption` - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + 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 content of the output message. + - `Auto = :none | :auto | :required` - - `class BetaResponseOutputText` + `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 text output from the model. + - `:none` - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `:auto` - The annotations of the text output. + - `:required` - - `class FileCitation` + - `class AssistantToolChoice` - A citation to a file. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `file_id: String` + - `type: :function | :code_interpreter | :file_search` - The ID of the file. + The type of the tool. If type is `function`, the function name must be set - - `filename: String` + - `:function` - The filename of the file cited. + - `:code_interpreter` - - `index: Integer` + - `:file_search` - The index of the file in the list of files. + - `function: AssistantToolChoiceFunction` - - `type: :file_citation` + - `name: String` - The type of the file citation. Always `file_citation`. + The name of the function to call. - - `:file_citation` + - `tools: Array[AssistantTool]` - - `class URLCitation` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - A citation for a web resource used to generate a model response. + - `class CodeInterpreterTool` + + - `type: :code_interpreter` - - `end_index: Integer` + The type of tool being defined: `code_interpreter` - The index of the last character of the URL citation in the message. + - `:code_interpreter` - - `start_index: Integer` + - `class FileSearchTool` - The index of the first character of the URL citation in the message. + - `type: :file_search` - - `title: String` + The type of tool being defined: `file_search` - The title of the web resource. + - `:file_search` - - `type: :url_citation` + - `file_search: FileSearch{ max_num_results, ranking_options}` - The type of the URL citation. Always `url_citation`. + Overrides for the file search tool. - - `:url_citation` + - `max_num_results: Integer` - - `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 web resource. + 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. - - `class ContainerFileCitation` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - A citation for a container file used to generate a model response. + 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. - - `container_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 ID of the container file. + - `score_threshold: Float` - - `end_index: Integer` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The index of the last character of the container file citation in the message. + - `ranker: :auto | :default_2024_08_21` - - `file_id: String` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The ID of the file. + - `:auto` - - `filename: String` + - `:default_2024_08_21` - The filename of the container file cited. + - `class FunctionTool` - - `start_index: Integer` + - `function: FunctionDefinition` - The index of the first character of the container file citation in the message. + - `name: String` - - `type: :container_file_citation` + 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 container file citation. Always `container_file_citation`. + - `description: String` - - `:container_file_citation` + A description of what the function does, used by the model to choose when and how to call the function. - - `class FilePath` + - `parameters: FunctionParameters` - A path to a file. + 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. - - `file_id: String` + Omitting `parameters` defines a function with an empty parameter list. - The ID of the file. + - `strict: bool` - - `index: Integer` + 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 index of the file in the list of files. + - `type: :function` - - `type: :file_path` + The type of tool being defined: `function` - The type of the file path. Always `file_path`. + - `:function` - - `:file_path` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - - `text: 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 text output from the model. + - `type: :auto | :last_messages` - - `type: :output_text` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The type of the output text. Always `output_text`. + - `:auto` - - `:output_text` + - `:last_messages` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `last_messages: Integer` - - `token: String` + The number of most recent messages from the thread when constructing the context for the run. - - `bytes: Array[Integer]` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - - `logprob: Float` + 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.). - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + - `completion_tokens: Integer` - - `token: String` + Number of completion tokens used over the course of the run. - - `bytes: Array[Integer]` + - `prompt_tokens: Integer` - - `logprob: Float` + Number of prompt tokens used over the course of the run. - - `class BetaResponseOutputRefusal` + - `total_tokens: Integer` - A refusal from the model. + Total number of tokens used (prompt + completion). - - `refusal: String` + - `temperature: Float` - The refusal explanation from the model. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: :refusal` + - `top_p: Float` - The type of the refusal. Always `refusal`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `:refusal` +### Example - - `role: :assistant` +```ruby +require "openai" - The role of the output message. Always `assistant`. +openai = OpenAI::Client.new(api_key: "My API Key") - - `:assistant` +run = openai.beta.threads.runs.create("thread_id", assistant_id: "assistant_id") - - `status: :in_progress | :completed | :incomplete` +puts(run) +``` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. +#### Response - - `:in_progress` +```json +{ + "id": "id", + "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 +} +``` - - `:completed` +## Retrieve run - - `:incomplete` +`beta.threads.runs.retrieve(run_id, **kwargs) -> Run` - - `type: :message` +**get** `/threads/{thread_id}/runs/{run_id}` - The type of the output message. Always `message`. +Retrieves a run. - - `:message` +### Parameters - - `agent: Agent{ agent_name}` +- `thread_id: String` - The agent that produced this item. +- `run_id: String` - - `agent_name: String` +### Returns - The canonical name of the agent that produced this item. +- `class Run` - - `phase: :commentary` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `id: String` - - `:commentary` + The identifier, which can be referenced in API endpoints. - - `class BetaResponseFileSearchToolCall` + - `assistant_id: String` - 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 ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `id: String` + - `cancelled_at: Integer` - The unique ID of the file search tool call. + The Unix timestamp (in seconds) for when the run was cancelled. - - `queries: Array[String]` + - `completed_at: Integer` - The queries used to search for files. + The Unix timestamp (in seconds) for when the run was completed. - - `status: :in_progress | :searching | :completed | 2 more` + - `created_at: Integer` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The Unix timestamp (in seconds) for when the run was created. - - `:in_progress` + - `expires_at: Integer` - - `:searching` + The Unix timestamp (in seconds) for when the run will expire. - - `:completed` + - `failed_at: Integer` - - `:incomplete` + The Unix timestamp (in seconds) for when the run failed. - - `:failed` + - `incomplete_details: IncompleteDetails{ reason}` - - `type: :file_search_call` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The type of the file search tool call. Always `file_search_call`. + - `reason: :max_completion_tokens | :max_prompt_tokens` - - `:file_search_call` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `agent: Agent{ agent_name}` + - `:max_completion_tokens` - The agent that produced this item. + - `:max_prompt_tokens` - - `agent_name: String` + - `instructions: String` - The canonical name of the agent that produced this item. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + - `last_error: LastError{ code, message}` - The results of the file search tool call. + The last error associated with this run. Will be `null` if there are no errors. - - `attributes: Hash[Symbol, String | Float | bool]` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - Set of 16 key-value pairs that can be attached to an object. 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. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `String = String` + - `:server_error` - - `Float = Float` + - `:rate_limit_exceeded` - - `UnionMember2 = bool` + - `:invalid_prompt` - - `file_id: String` + - `message: String` - The unique ID of the file. + A human-readable description of the error. - - `filename: String` + - `max_completion_tokens: Integer` - The name of the file. + The maximum number of completion tokens specified to have been used over the course of the run. - - `score: Float` + - `max_prompt_tokens: Integer` - The relevance score of the file - a value between 0 and 1. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `text: String` + - `metadata: Metadata` - The text that was retrieved from the file. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class BetaResponseComputerToolCall` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - 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. + - `model: String` - - `id: String` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The unique ID of the computer call. + - `object: :"thread.run"` - - `call_id: String` + The object type, which is always `thread.run`. - An identifier used when responding to the tool call with output. + - `:"thread.run"` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + - `parallel_tool_calls: bool` - The pending safety checks for the computer call. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `id: String` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - The ID of the pending safety check. + Details on the action required to continue the run. Will be `null` if no action is required. - - `code: String` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - The type of the pending safety check. + Details on the tool outputs needed for this run to continue. - - `message: String` + - `tool_calls: Array[RequiredActionFunctionToolCall]` - Details about the pending safety check. + A list of the relevant tool calls. - - `status: :in_progress | :completed | :incomplete` + - `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 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. - - `:in_progress` + - `function: Function{ arguments, name}` - - `:completed` + The function definition. - - `:incomplete` + - `arguments: String` - - `type: :computer_call` + The arguments that the model expects you to pass to the function. - The type of the computer call. Always `computer_call`. + - `name: String` - - `:computer_call` + The name of the function. - - `action: BetaComputerAction` + - `type: :function` - A click action. + The type of tool call the output is required for. For now, this is always `function`. - - `class Click` + - `:function` - A click action. + - `type: :submit_tool_outputs` - - `button: :left | :right | :wheel | 2 more` + For now, this is always `submit_tool_outputs`. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `:submit_tool_outputs` - - `:left` + - `response_format: AssistantResponseFormatOption` - - `:right` + 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`. - - `:wheel` + 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). - - `:back` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `:forward` + **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. - - `type: :click` + - `AssistantResponseFormatOption = :auto` - Specifies the event type. For a click action, this property is always `click`. + `auto` is the default value - - `:click` + - `:auto` - - `x: Integer` + - `class ResponseFormatText` - The x-coordinate where the click occurred. + Default response format. Used to generate text responses. - - `y_: Integer` + - `type: :text` - The y-coordinate where the click occurred. + The type of response format being defined. Always `text`. - - `keys: Array[String]` + - `:text` - The keys being held while clicking. + - `class ResponseFormatJSONObject` - - `class DoubleClick` + 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 double click action. + - `type: :json_object` - - `keys: Array[String]` + The type of response format being defined. Always `json_object`. - The keys being held while double-clicking. + - `:json_object` - - `type: :double_click` + - `class ResponseFormatJSONSchema` - Specifies the event type. For a double click action, this property is always set to `double_click`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:double_click` + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `x: Integer` + Structured Outputs configuration options, including a JSON Schema. - The x-coordinate where the double click occurred. + - `name: String` - - `y_: Integer` + 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 y-coordinate where the double click occurred. + - `description: String` - - `class Drag` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A drag action. + - `schema: Hash[Symbol, untyped]` - - `path: Array[Path{ x, y_}]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `strict: bool` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + 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). - - `x: Integer` + - `type: :json_schema` - The x-coordinate. + The type of response format being defined. Always `json_schema`. - - `y_: Integer` + - `:json_schema` - The y-coordinate. + - `started_at: Integer` - - `type: :drag` + The Unix timestamp (in seconds) for when the run was started. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `status: RunStatus` - - `:drag` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `keys: Array[String]` + - `:queued` - The keys being held while dragging the mouse. + - `:in_progress` - - `class Keypress` + - `:requires_action` - A collection of keypresses the model would like to perform. + - `:cancelling` - - `keys: Array[String]` + - `:cancelled` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `:failed` - - `type: :keypress` + - `:completed` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `:incomplete` - - `:keypress` + - `:expired` - - `class Move` + - `thread_id: String` - A mouse move action. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `type: :move` + - `tool_choice: AssistantToolChoiceOption` - Specifies the event type. For a move action, this property is always set to `move`. + 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. - - `:move` + - `Auto = :none | :auto | :required` - - `x: Integer` + `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 x-coordinate to move to. + - `:none` - - `y_: Integer` + - `:auto` - The y-coordinate to move to. + - `:required` - - `keys: Array[String]` + - `class AssistantToolChoice` - The keys being held while moving the mouse. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `class Screenshot` + - `type: :function | :code_interpreter | :file_search` - A screenshot action. + The type of the tool. If type is `function`, the function name must be set - - `type: :screenshot` + - `:function` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `:code_interpreter` - - `:screenshot` + - `:file_search` - - `class Scroll` + - `function: AssistantToolChoiceFunction` - A scroll action. + - `name: String` - - `scroll_x: Integer` + The name of the function to call. - The horizontal scroll distance. + - `tools: Array[AssistantTool]` - - `scroll_y: Integer` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The vertical scroll distance. + - `class CodeInterpreterTool` - - `type: :scroll` + - `type: :code_interpreter` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The type of tool being defined: `code_interpreter` - - `:scroll` + - `:code_interpreter` - - `x: Integer` + - `class FileSearchTool` - The x-coordinate where the scroll occurred. + - `type: :file_search` - - `y_: Integer` + The type of tool being defined: `file_search` - The y-coordinate where the scroll occurred. + - `:file_search` - - `keys: Array[String]` + - `file_search: FileSearch{ max_num_results, ranking_options}` - The keys being held while scrolling. + Overrides for the file search tool. - - `class Type` + - `max_num_results: Integer` - 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. - - `text: 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 text to type. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `type: :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. - Specifies the event type. For a type action, this property is always set to `type`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `:type` + - `score_threshold: Float` - - `class Wait` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A wait action. + - `ranker: :auto | :default_2024_08_21` - - `type: :wait` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `:auto` - - `:wait` + - `:default_2024_08_21` - - `actions: BetaComputerActionList` + - `class FunctionTool` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `function: FunctionDefinition` - - `class Click` + - `name: String` - A click action. + 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. - - `class DoubleClick` + - `description: String` - A double click action. + A description of what the function does, used by the model to choose when and how to call the function. - - `class Drag` + - `parameters: FunctionParameters` - A drag action. + 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. - - `class Keypress` + Omitting `parameters` defines a function with an empty parameter list. - A collection of keypresses the model would like to perform. + - `strict: bool` - - `class Move` + 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 mouse move action. + - `type: :function` - - `class Screenshot` + The type of tool being defined: `function` - A screenshot action. + - `:function` - - `class Scroll` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - A scroll action. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `class Type` + - `type: :auto | :last_messages` - An action to type in text. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `class Wait` + - `:auto` - A wait action. + - `:last_messages` - - `agent: Agent{ agent_name}` + - `last_messages: Integer` - 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: Usage{ 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.). - - `class BetaResponseComputerToolCallOutputItem` + - `completion_tokens: Integer` - - `id: String` + Number of completion tokens used over the course of the run. - The unique ID of the computer call tool output. + - `prompt_tokens: Integer` - - `call_id: String` + Number of prompt tokens used over the course of the run. - The ID of the computer tool call that produced the output. + - `total_tokens: Integer` - - `output: BetaResponseComputerToolCallOutputScreenshot` + Total number of tokens used (prompt + completion). - A computer screenshot image used with the computer use tool. + - `temperature: Float` - - `type: :computer_screenshot` + The sampling temperature used for this run. If not set, defaults to 1. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `top_p: Float` - - `:computer_screenshot` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `file_id: String` +### Example - The identifier of an uploaded file that contains the screenshot. +```ruby +require "openai" - - `image_url: String` +openai = OpenAI::Client.new(api_key: "My API Key") - The URL of the screenshot image. +run = openai.beta.threads.runs.retrieve("run_id", thread_id: "thread_id") - - `status: :completed | :incomplete | :failed | :in_progress` +puts(run) +``` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. +#### Response - - `:completed` +```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 +} +``` - - `:incomplete` +## Modify run - - `:failed` +`beta.threads.runs.update(run_id, **kwargs) -> Run` - - `:in_progress` +**post** `/threads/{thread_id}/runs/{run_id}` - - `type: :computer_call_output` +Modifies a run. - The type of the computer tool call output. Always `computer_call_output`. +### Parameters - - `:computer_call_output` +- `thread_id: String` - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` +- `run_id: String` - The safety checks reported by the API that have been acknowledged by the - developer. +- `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 ID of the pending safety check. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `code: String` +### Returns - The type of the pending safety check. +- `class Run` - - `message: String` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - Details about the pending safety check. + - `id: String` - - `agent: Agent{ agent_name}` + The identifier, which can be referenced in API endpoints. - The agent that produced this item. + - `assistant_id: String` - - `agent_name: String` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The canonical name of the agent that produced this item. + - `cancelled_at: Integer` - - `created_by: String` + The Unix timestamp (in seconds) for when the run was cancelled. - The identifier of the actor that created the item. + - `completed_at: Integer` - - `class BetaResponseFunctionWebSearch` + The Unix timestamp (in seconds) for when the run was completed. - 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. + - `created_at: Integer` - - `id: String` + The Unix timestamp (in seconds) for when the run was created. - The unique ID of the web search tool call. + - `expires_at: Integer` - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + The Unix timestamp (in seconds) for when the run will expire. - 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). + - `failed_at: Integer` - - `class Search` + The Unix timestamp (in seconds) for when the run failed. - Action type "search" - Performs a web search query. + - `incomplete_details: IncompleteDetails{ reason}` - - `type: :search` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The action type. + - `reason: :max_completion_tokens | :max_prompt_tokens` - - `:search` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `queries: Array[String]` + - `:max_completion_tokens` - The search queries. + - `:max_prompt_tokens` - - `query: String` + - `instructions: String` - The search query. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `sources: Array[Source{ type, url}]` + - `last_error: LastError{ code, message}` - The sources used in the search. + The last error associated with this run. Will be `null` if there are no errors. - - `type: :url` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - The type of source. Always `url`. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `:url` + - `:server_error` - - `url: String` + - `:rate_limit_exceeded` - The URL of the source. + - `:invalid_prompt` - - `class OpenPage` + - `message: String` - Action type "open_page" - Opens a specific URL from search results. + A human-readable description of the error. - - `type: :open_page` + - `max_completion_tokens: Integer` - The action type. + The maximum number of completion tokens specified to have been used over the course of the run. - - `:open_page` + - `max_prompt_tokens: Integer` - - `url: String` + The maximum number of prompt tokens specified to have been used over the course of the run. - The URL opened by the model. + - `metadata: Metadata` - - `class FindInPage` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Action type "find_in_page": Searches for a pattern within a loaded page. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `pattern: String` + - `model: String` - The pattern or text to search for within the page. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: :find_in_page` + - `object: :"thread.run"` - The action type. + The object type, which is always `thread.run`. - - `:find_in_page` + - `:"thread.run"` - - `url: String` + - `parallel_tool_calls: bool` - The URL of the page searched for the pattern. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `status: :in_progress | :searching | :completed | :failed` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - The status of the web search tool call. + Details on the action required to continue the run. Will be `null` if no action is required. - - `:in_progress` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - - `:searching` + Details on the tool outputs needed for this run to continue. - - `:completed` + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `:failed` + A list of the relevant tool calls. - - `type: :web_search_call` + - `id: String` - The type of the web search tool call. Always `web_search_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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `:web_search_call` + - `function: Function{ arguments, name}` - - `agent: Agent{ agent_name}` + The function definition. - The agent that produced this item. + - `arguments: String` - - `agent_name: String` + The arguments that the model expects you to pass to the function. - The canonical name of the agent that produced this item. + - `name: String` - - `class BetaResponseFunctionToolCallItem` + The name of the function. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `type: :function` - - `id: String` + The type of tool call the output is required for. For now, this is always `function`. - The unique ID of the function tool call. + - `:function` - - `status: :in_progress | :completed | :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](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`. - - `created_by: 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 identifier of the actor that created the item. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class BetaResponseFunctionToolCallOutputItem` + **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` + - `AssistantResponseFormatOption = :auto` - The unique ID of the function call tool output. + `auto` is the default value - - `call_id: String` + - `:auto` - The unique ID of the function tool call generated by the model. + - `class ResponseFormatText` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + Default response format. Used to generate text responses. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: :text` - - `String = String` + The type of response format being defined. Always `text`. - A string of the output of the function call. + - `:text` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `class ResponseFormatJSONObject` - Text, image, or file output of the function 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. - - `class BetaResponseInputText` + - `type: :json_object` - A text input to the model. + The type of response format being defined. Always `json_object`. - - `class BetaResponseInputImage` + - `:json_object` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class ResponseFormatJSONSchema` - - `class BetaResponseInputFile` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - A file input to the model. + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `status: :in_progress | :completed | :incomplete` + Structured Outputs configuration options, including a JSON Schema. - 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 response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `:completed` + - `description: String` - - `:incomplete` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: :function_call_output` + - `schema: Hash[Symbol, untyped]` - The type of the function tool call output. Always `function_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/). - - `:function_call_output` + - `strict: bool` - - `agent: Agent{ 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_: Direct{ type} | Program{ caller_id, type}` + - `started_at: Integer` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the run was started. - - `class Direct` + - `status: RunStatus` - - `type: :direct` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The caller type. Always `direct`. + - `:queued` - - `:direct` + - `:in_progress` - - `class Program` + - `:requires_action` - - `caller_id: String` + - `:cancelling` - The call ID of the program item that produced this tool call. + - `:cancelled` - - `type: :program` + - `:failed` - The caller type. Always `program`. + - `:completed` - - `:program` + - `:incomplete` - - `created_by: String` + - `:expired` - The identifier of the actor that created the item. + - `thread_id: String` - - `class AgentMessage` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `id: String` + - `tool_choice: AssistantToolChoiceOption` - The unique ID of the agent message. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `author: String` + - `Auto = :none | :auto | :required` - The sending agent identity. + `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[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `:none` - Encrypted content sent between agents. + - `:auto` - - `class BetaResponseInputText` + - `:required` - A text input to the model. + - `class AssistantToolChoice` - - `class BetaResponseOutputText` + Specifies a tool the model should use. Use to force the model to call a specific tool. - A text output from the model. + - `type: :function | :code_interpreter | :file_search` - - `class Text` + The type of the tool. If type is `function`, the function name must be set - A text content. + - `:function` - - `text: String` + - `:code_interpreter` - - `type: :text` + - `:file_search` - - `:text` + - `function: AssistantToolChoiceFunction` - - `class SummaryText` + - `name: String` - A summary text from the model. + The name of the function to call. - - `text: String` + - `tools: Array[AssistantTool]` - A summary of the reasoning output from the model so far. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: :summary_text` + - `class CodeInterpreterTool` - The type of the object. Always `summary_text`. + - `type: :code_interpreter` - - `:summary_text` + The type of tool being defined: `code_interpreter` - - `class ReasoningText` + - `:code_interpreter` - Reasoning text from the model. + - `class FileSearchTool` - - `text: String` + - `type: :file_search` - The reasoning text from the model. + The type of tool being defined: `file_search` - - `type: :reasoning_text` + - `:file_search` - The type of the reasoning text. Always `reasoning_text`. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `:reasoning_text` + Overrides for the file search tool. - - `class BetaResponseOutputRefusal` + - `max_num_results: Integer` - A refusal from 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. - - `class BetaResponseInputImage` + 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `class ComputerScreenshot` + 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 screenshot of a computer. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `detail: :low | :high | :auto | :original` + - `score_threshold: Float` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `:low` + - `ranker: :auto | :default_2024_08_21` - - `:high` + The ranker to use for the file search. If not specified will use the `auto` ranker. - `:auto` - - `:original` + - `:default_2024_08_21` - - `file_id: String` + - `class FunctionTool` - The identifier of an uploaded file that contains the screenshot. + - `function: FunctionDefinition` - - `image_url: String` + - `name: String` - The URL of the screenshot image. + 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: :computer_screenshot` + - `description: String` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + A description of what the function does, used by the model to choose when and how to call the function. - - `:computer_screenshot` + - `parameters: FunctionParameters` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + 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. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Omitting `parameters` defines a function with an empty parameter list. - - `mode: :explicit` + - `strict: bool` - The breakpoint mode. Always `explicit`. + 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). - - `:explicit` + - `type: :function` - - `class BetaResponseInputFile` + The type of tool being defined: `function` - A file input to the model. + - `:function` - - `class EncryptedContent` + - `truncation_strategy: TruncationStrategy{ 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 | :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: Integer` - - `recipient: String` + The number of most recent messages from the thread when constructing the context for the run. - The destination agent identity. + - `usage: Usage{ 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 type of the item. Always `agent_message`. + - `completion_tokens: Integer` - - `:agent_message` + Number of completion tokens used over the course of the run. - - `agent: Agent{ agent_name}` + - `prompt_tokens: Integer` - The agent that produced this item. + Number of prompt tokens used over the course of the run. - - `agent_name: String` + - `total_tokens: Integer` - The canonical name of the agent that produced this item. + Total number of tokens used (prompt + completion). - - `class MultiAgentCall` + - `temperature: Float` - - `id: String` + The sampling temperature used for this run. If not set, defaults to 1. - The unique ID of the multi-agent call item. + - `top_p: Float` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + The nucleus sampling value used for this run. If not set, defaults to 1. - The multi-agent action to execute. +### Example - - `:spawn_agent` +```ruby +require "openai" - - `:interrupt_agent` +openai = OpenAI::Client.new(api_key: "My API Key") - - `:list_agents` +run = openai.beta.threads.runs.update("run_id", thread_id: "thread_id") - - `:send_message` +puts(run) +``` - - `:followup_task` +#### Response - - `:wait_agent` +```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 +} +``` - - `arguments: String` +## Submit tool outputs to run - The JSON string of arguments generated for the action. +`beta.threads.runs.submit_tool_outputs(run_id, **kwargs) -> Run` - - `call_id: String` +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - The unique ID linking this call to its output. +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: :multi_agent_call` +### Parameters - The type of the multi-agent call. Always `multi_agent_call`. +- `thread_id: String` - - `:multi_agent_call` +- `run_id: String` - - `agent: Agent{ agent_name}` +- `tool_outputs: Array[ToolOutput{ output, tool_call_id}]` - The agent that produced this item. + A list of tools for which the outputs are being submitted. - - `agent_name: String` + - `output: String` - The canonical name of the agent that produced this item. + The output of the tool call to be submitted to continue the run. - - `class MultiAgentCallOutput` + - `tool_call_id: String` - - `id: String` + The ID of the tool call in the `required_action` object within the run object the output is being submitted for. - The unique ID of the multi-agent call output item. +- `stream: bool` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 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 multi-agent action that produced this result. +### Returns - - `:spawn_agent` +- `class Run` - - `:interrupt_agent` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `:list_agents` + - `id: String` - - `:send_message` + The identifier, which can be referenced in API endpoints. - - `:followup_task` + - `assistant_id: String` - - `:wait_agent` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `call_id: String` + - `cancelled_at: Integer` - The unique ID of the multi-agent call. + The Unix timestamp (in seconds) for when the run was cancelled. - - `output: Array[BetaResponseOutputText]` + - `completed_at: Integer` - Text output returned by the multi-agent action. + The Unix timestamp (in seconds) for when the run was completed. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + - `created_at: Integer` - The annotations of the text output. + The Unix timestamp (in seconds) for when the run was created. - - `text: String` + - `expires_at: Integer` - The text output from the model. + The Unix timestamp (in seconds) for when the run will expire. - - `type: :output_text` + - `failed_at: Integer` - The type of the output text. Always `output_text`. + The Unix timestamp (in seconds) for when the run failed. - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `incomplete_details: IncompleteDetails{ reason}` - - `type: :multi_agent_call_output` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `reason: :max_completion_tokens | :max_prompt_tokens` - - `:multi_agent_call_output` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `agent: Agent{ agent_name}` + - `:max_completion_tokens` - The agent that produced this item. + - `:max_prompt_tokens` - - `agent_name: String` + - `instructions: String` - The canonical name of the agent that produced this item. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `class BetaResponseToolSearchCall` + - `last_error: LastError{ code, message}` - - `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 item. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - - `arguments: untyped` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - Arguments used for the tool search call. + - `:server_error` - - `call_id: String` + - `:rate_limit_exceeded` - The unique ID of the tool search call generated by the model. + - `:invalid_prompt` - - `execution: :server | :client` + - `message: String` - Whether tool search was executed by the server or by the client. + A human-readable description of the error. - - `:server` + - `max_completion_tokens: Integer` - - `:client` + The maximum number of completion tokens specified to have been used over the course of the run. - - `status: :in_progress | :completed | :incomplete` + - `max_prompt_tokens: Integer` - The status of the tool search call item that was recorded. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `:in_progress` + - `metadata: 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. - - `type: :tool_search_call` + - `model: String` - The type of the item. Always `tool_search_call`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `:tool_search_call` + - `object: :"thread.run"` - - `agent: Agent{ agent_name}` + The object type, which is always `thread.run`. - The agent that produced this item. + - `:"thread.run"` - - `agent_name: String` + - `parallel_tool_calls: bool` - 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. - - `created_by: String` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - The identifier of the actor that created the item. + Details on the action required to continue the run. Will be `null` if no action is required. - - `class BetaResponseToolSearchOutputItem` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - - `id: String` + Details on the tool outputs needed for this run to continue. - The unique ID of the tool search output item. + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `call_id: String` + A list of the relevant tool calls. - The unique ID of the tool search call generated by the model. + - `id: String` - - `execution: :server | :client` + 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. - Whether tool search was executed by the server or by the client. + - `function: Function{ arguments, name}` - - `:server` + The function definition. - - `:client` + - `arguments: String` - - `status: :in_progress | :completed | :incomplete` + The arguments that the model expects you to pass to the function. - The status of the tool search output item that was recorded. + - `name: String` - - `:in_progress` + The name of the function. - - `:completed` + - `type: :function` - - `:incomplete` + The type of tool call the output is required for. For now, this is always `function`. - - `tools: Array[BetaTool]` + - `:function` - The loaded tool definitions returned by tool search. + - `type: :submit_tool_outputs` - - `class BetaFunctionTool` + For now, this is always `submit_tool_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). + - `:submit_tool_outputs` - - `name: String` + - `response_format: AssistantResponseFormatOption` - The name of the function to 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`. - - `parameters: Hash[Symbol, untyped]` + 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). - A JSON schema object describing the parameters of the function. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `strict: bool` + **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 strict parameter validation is enforced for this function tool. + - `AssistantResponseFormatOption = :auto` - - `type: :function` + `auto` is the default value - The type of the function tool. Always `function`. + - `:auto` - - `:function` + - `class ResponseFormatText` - - `allowed_callers: Array[:direct | :programmatic]` + Default response format. Used to generate text responses. - The tool invocation context(s). + - `type: :text` - - `:direct` + The type of response format being defined. Always `text`. - - `:programmatic` + - `:text` - - `defer_loading: bool` + - `class ResponseFormatJSONObject` - Whether this function is deferred and loaded via tool search. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `description: String` + - `type: :json_object` - 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 `json_object`. - - `output_schema: Hash[Symbol, untyped]` + - `:json_object` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class ResponseFormatJSONSchema` - - `class BetaFileSearchTool` + 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). + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `type: :file_search` + Structured Outputs configuration options, including a JSON Schema. - The type of the file search tool. Always `file_search`. + - `name: String` - - `: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. - - `vector_store_ids: Array[String]` + - `description: String` - The IDs of the vector stores to search. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + - `schema: Hash[Symbol, untyped]` - A filter to apply. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `class ComparisonFilter` + - `strict: bool` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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). - - `key: String` + - `type: :json_schema` - The key to compare against the value. + The type of response format being defined. Always `json_schema`. - - `type: :eq | :ne | :gt | 5 more` + - `:json_schema` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `started_at: Integer` - - `eq`: equals - - `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 was started. - - `:eq` + - `status: RunStatus` - - `:ne` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `:gt` + - `:queued` - - `:gte` + - `:in_progress` - - `:lt` + - `:requires_action` - - `:lte` + - `:cancelling` - - `:in` + - `:cancelled` - - `:nin` + - `:failed` - - `value: String | Float | bool | Array[untyped]` + - `:completed` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:incomplete` - - `String = String` + - `:expired` - - `Float = Float` + - `thread_id: String` - - `UnionMember2 = bool` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `UnionMember3 = Array[untyped]` + - `tool_choice: AssistantToolChoiceOption` - - `class CompoundFilter` + 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. - Combine multiple filters using `and` or `or`. + - `Auto = :none | :auto | :required` - - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + `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. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `:none` - - `class ComparisonFilter` + - `:auto` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `:required` - - `key: String` + - `class AssistantToolChoice` - The key to compare against the value. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `type: :eq | :ne | :gt | 5 more` + - `type: :function | :code_interpreter | :file_search` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the tool. If type is `function`, the function name must be set - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `:function` - - `:eq` + - `:code_interpreter` - - `:ne` + - `:file_search` - - `:gt` + - `function: AssistantToolChoiceFunction` - - `:gte` + - `name: String` - - `:lt` + The name of the function to call. - - `:lte` + - `tools: Array[AssistantTool]` - - `:in` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `:nin` + - `class CodeInterpreterTool` - - `value: String | Float | bool | Array[untyped]` + - `type: :code_interpreter` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of tool being defined: `code_interpreter` - - `String = String` + - `:code_interpreter` - - `Float = Float` + - `class FileSearchTool` - - `UnionMember2 = bool` + - `type: :file_search` - - `UnionMember3 = Array[untyped]` + The type of tool being defined: `file_search` - - `UnionMember1 = untyped` + - `:file_search` - - `type: :and | :or` + - `file_search: FileSearch{ max_num_results, ranking_options}` - Type of operation: `and` or `or`. + Overrides for the file search tool. - - `:and` + - `max_num_results: Integer` - - `: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: Integer` + 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: RankingOptions{ score_threshold, ranker}` - - `ranking_options: RankingOptions{ 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: HybridSearch{ embedding_weight, text_weight}` + - `score_threshold: Float` - 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: Float` + - `ranker: :auto | :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: Float` + - `:auto` - The weight of the text in the reciprocal ranking fusion. + - `:default_2024_08_21` - - `ranker: :auto | :"default-2024-11-15"` + - `class FunctionTool` - 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: Float` + - `description: 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. - - `class BetaComputerTool` + - `parameters: 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: bool` - - `: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). - - `class BetaComputerUsePreviewTool` + - `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: Integer` + - `:function` - The height of the computer display. + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - - `display_width: Integer` + 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 | :last_messages` - - `environment: :windows | :mac | :linux | 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: Integer` - - `:linux` + The number of most recent messages from the thread when constructing the context for the run. - - `:ubuntu` + - `usage: Usage{ 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: Integer` - 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: Integer` - - `class BetaWebSearchTool` + 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](https://platform.openai.com/docs/guides/tools-web-search). + - `total_tokens: Integer` - - `type: :web_search | :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: Float` - - `:web_search` + The sampling temperature used for this run. If not set, defaults to 1. - - `:web_search_2025_08_26` + - `top_p: Float` - - `filters: Filters{ allowed_domains}` + The nucleus sampling value used for this run. If not set, defaults to 1. - Filters for the search. +### Example - - `allowed_domains: Array[String]` +```ruby +require "openai" - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +openai = OpenAI::Client.new(api_key: "My API Key") - Example: `["pubmed.ncbi.nlm.nih.gov"]` +run = openai.beta.threads.runs.submit_tool_outputs("run_id", thread_id: "thread_id", tool_outputs: [{}]) - - `search_context_size: :low | :medium | :high` +puts(run) +``` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. +#### Response - - `:low` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `:medium` +## Cancel a run - - `:high` +`beta.threads.runs.cancel(run_id, **kwargs) -> Run` - - `user_location: UserLocation{ city, country, region, 2 more}` +**post** `/threads/{thread_id}/runs/{run_id}/cancel` - The approximate location of the user. +Cancels a run that is `in_progress`. - - `city: String` +### Parameters - Free text input for the city of the user, e.g. `San Francisco`. +- `thread_id: String` - - `country: String` +- `run_id: String` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. +### Returns - - `region: String` +- `class Run` - Free text input for the region of the user, e.g. `California`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `timezone: String` + - `id: String` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The identifier, which can be referenced in API endpoints. - - `type: :approximate` + - `assistant_id: String` - The type of location approximation. Always `approximate`. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `:approximate` + - `cancelled_at: Integer` - - `class Mcp` + The Unix timestamp (in seconds) for when the run was cancelled. - 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_at: Integer` - - `server_label: String` + The Unix timestamp (in seconds) for when the run was completed. - A label for this MCP server, used to identify it in tool calls. + - `created_at: Integer` - - `type: :mcp` + The Unix timestamp (in seconds) for when the run was created. - The type of the MCP tool. Always `mcp`. + - `expires_at: Integer` - - `:mcp` + The Unix timestamp (in seconds) for when the run will expire. - - `allowed_callers: Array[:direct | :programmatic]` + - `failed_at: Integer` - The tool invocation context(s). + The Unix timestamp (in seconds) for when the run failed. - - `:direct` + - `incomplete_details: IncompleteDetails{ reason}` - - `:programmatic` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + - `reason: :max_completion_tokens | :max_prompt_tokens` - List of allowed tool names or a filter object. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `McpAllowedTools = Array[String]` + - `:max_completion_tokens` - A string array of allowed tool names + - `:max_prompt_tokens` - - `class McpToolFilter` + - `instructions: String` - A filter object to specify which tools are allowed. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `read_only: bool` + - `last_error: LastError{ code, 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. + The last error associated with this run. Will be `null` if there are no errors. - - `tool_names: Array[String]` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - List of allowed tool names. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `authorization: String` + - `:server_error` - 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. + - `:rate_limit_exceeded` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + - `:invalid_prompt` - 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). + - `message: String` - Currently supported `connector_id` values are: + A human-readable description of the error. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `max_completion_tokens: Integer` - - `:connector_dropbox` + The maximum number of completion tokens specified to have been used over the course of the run. - - `:connector_gmail` + - `max_prompt_tokens: Integer` - - `:connector_googlecalendar` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `:connector_googledrive` + - `metadata: Metadata` - - `:connector_microsoftteams` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `:connector_outlookcalendar` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `:connector_outlookemail` + - `model: String` - - `:connector_sharepoint` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `defer_loading: bool` + - `object: :"thread.run"` - Whether this MCP tool is deferred and discovered via tool search. + The object type, which is always `thread.run`. - - `headers: Hash[Symbol, String]` + - `:"thread.run"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `parallel_tool_calls: bool` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - Specify which of the MCP server's tools require approval. + - `required_action: RequiredAction{ submit_tool_outputs, type}` - - `class McpToolApprovalFilter` + Details on the action required to continue the run. Will be `null` if no action is required. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - - `always: Always{ read_only, tool_names}` + Details on the tool outputs needed for this run to continue. - A filter object to specify which tools are allowed. + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `read_only: bool` + A list of the relevant 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. + - `id: String` - - `tool_names: Array[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. - List of allowed tool names. + - `function: Function{ arguments, name}` - - `never: Never{ read_only, tool_names}` + The function definition. - A filter object to specify which tools are allowed. + - `arguments: String` - - `read_only: bool` + The arguments that the model expects you to pass to the function. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `name: String` - - `tool_names: Array[String]` + The name of the function. - List of allowed tool names. + - `type: :function` - - `McpToolApprovalSetting = :always | :never` + The type of tool call the output is required for. For now, this is always `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. + - `:function` - - `:always` + - `type: :submit_tool_outputs` - - `:never` + For now, this is always `submit_tool_outputs`. - - `server_description: String` + - `:submit_tool_outputs` - Optional description of the MCP server, used to provide more context. + - `response_format: AssistantResponseFormatOption` - - `server_url: 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 URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + 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). - - `tunnel_id: String` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - 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. + **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. - - `class CodeInterpreter` + - `AssistantResponseFormatOption = :auto` - A tool that runs Python code to help generate a response to a prompt. + `auto` is the default value - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `: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. + - `class ResponseFormatText` - - `String = String` + Default response format. Used to generate text responses. - The container ID. + - `type: :text` - - `class CodeInterpreterToolAuto` + The type of response format being defined. Always `text`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `:text` - - `type: :auto` + - `class ResponseFormatJSONObject` - Always `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. - - `:auto` + - `type: :json_object` - - `file_ids: Array[String]` + The type of response format being defined. Always `json_object`. - An optional list of uploaded files to make available to your code. + - `:json_object` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `class ResponseFormatJSONSchema` - The memory limit for the code interpreter container. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `:"1g"` + - `json_schema: JSONSchema{ name, description, schema, strict}` - - `:"4g"` + Structured Outputs configuration options, including a JSON Schema. - - `:"16g"` + - `name: String` - - `:"64g"` + 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_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `description: String` - Network access policy for the container. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaContainerNetworkPolicyDisabled` + - `schema: Hash[Symbol, untyped]` - - `type: :disabled` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Disable outbound network access. Always `disabled`. + - `strict: bool` - - `:disabled` + 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). - - `class BetaContainerNetworkPolicyAllowlist` + - `type: :json_schema` - - `allowed_domains: Array[String]` + The type of response format being defined. Always `json_schema`. - A list of allowed domains when type is `allowlist`. + - `:json_schema` - - `type: :allowlist` + - `started_at: Integer` - Allow outbound network access only to specified domains. Always `allowlist`. + The Unix timestamp (in seconds) for when the run was started. - - `:allowlist` + - `status: RunStatus` - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - Optional domain-scoped secrets for allowlisted domains. + - `:queued` - - `domain: String` + - `:in_progress` - The domain associated with the secret. + - `:requires_action` - - `name: String` + - `:cancelling` - The name of the secret to inject for the domain. + - `:cancelled` - - `value: String` + - `:failed` - The secret value to inject for the domain. + - `:completed` - - `type: :code_interpreter` + - `:incomplete` - The type of the code interpreter tool. Always `code_interpreter`. + - `:expired` - - `:code_interpreter` + - `thread_id: String` - - `allowed_callers: Array[:direct | :programmatic]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The tool invocation context(s). + - `tool_choice: AssistantToolChoiceOption` - - `:direct` + 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. - - `:programmatic` + - `Auto = :none | :auto | :required` - - `class ProgrammaticToolCalling` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `type: :programmatic_tool_calling` + - `:none` - The type of the tool. Always `programmatic_tool_calling`. + - `:auto` - - `:programmatic_tool_calling` + - `:required` - - `class ImageGeneration` + - `class AssistantToolChoice` - A tool that generates images using the GPT image models. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `type: :image_generation` + - `type: :function | :code_interpreter | :file_search` - The type of the image generation tool. Always `image_generation`. + The type of the tool. If type is `function`, the function name must be set - - `:image_generation` + - `:function` - - `action: :generate | :edit | :auto` + - `:code_interpreter` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `:file_search` - - `:generate` + - `function: AssistantToolChoiceFunction` - - `:edit` + - `name: String` - - `:auto` + The name of the function to call. - - `background: :transparent | :opaque | :auto` + - `tools: Array[AssistantTool]` - 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 list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - `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. + - `class CodeInterpreterTool` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: :code_interpreter` - - `:transparent` + The type of tool being defined: `code_interpreter` - - `:opaque` + - `:code_interpreter` - - `:auto` + - `class FileSearchTool` - - `input_fidelity: :high | :low` + - `type: :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 tool being defined: `file_search` - - `:high` + - `:file_search` - - `:low` + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `input_image_mask: InputImageMask{ file_id, image_url}` + Overrides for the file search tool. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `max_num_results: Integer` - - `file_id: 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. - File ID for the mask image. + 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. - - `image_url: String` + - `ranking_options: RankingOptions{ score_threshold, ranker}` - Base64-encoded mask image. + 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. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The image generation model to use. Default: `gpt-image-1`. + - `score_threshold: Float` - - `String = String` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `ranker: :auto | :default_2024_08_21` - The image generation model to use. Default: `gpt-image-1`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `:"gpt-image-1"` + - `:auto` - - `:"gpt-image-1-mini"` + - `:default_2024_08_21` - - `:"gpt-image-2"` + - `class FunctionTool` - - `:"gpt-image-2-2026-04-21"` + - `function: FunctionDefinition` - - `:"gpt-image-1.5"` + - `name: String` - - `:"chatgpt-image-latest"` + 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. - - `moderation: :auto | :low` + - `description: String` - Moderation level for the generated image. Default: `auto`. + A description of what the function does, used by the model to choose when and how to call the function. - - `:auto` + - `parameters: FunctionParameters` - - `:low` + 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. - - `output_compression: Integer` + Omitting `parameters` defines a function with an empty parameter list. - Compression level for the output image. Default: 100. + - `strict: bool` - - `output_format: :png | :webp | :jpeg` + 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 output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: :function` - - `:png` + The type of tool being defined: `function` - - `:webp` + - `:function` - - `:jpeg` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - - `partial_images: Integer` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: :auto | :last_messages` - - `quality: :low | :medium | :high | :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`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `:auto` - - `:low` + - `:last_messages` - - `:medium` + - `last_messages: Integer` - - `:high` + The number of most recent messages from the thread when constructing the context for the run. - - `:auto` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + 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 size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `completion_tokens: Integer` - - `String = String` + Number of completion tokens used over the course of the run. - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + - `prompt_tokens: Integer` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Number of prompt tokens used over the course of the run. - - `:"1024x1024"` + - `total_tokens: Integer` - - `:"1024x1536"` + Total number of tokens used (prompt + completion). - - `:"1536x1024"` + - `temperature: Float` - - `:auto` + The sampling temperature used for this run. If not set, defaults to 1. - - `class LocalShell` + - `top_p: Float` - A tool that allows the model to execute shell commands in a local environment. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `type: :local_shell` +### Example - The type of the local shell tool. Always `local_shell`. +```ruby +require "openai" - - `:local_shell` +openai = OpenAI::Client.new(api_key: "My API Key") - - `class BetaFunctionShellTool` +run = openai.beta.threads.runs.cancel("run_id", thread_id: "thread_id") - A tool that allows the model to execute shell commands. +puts(run) +``` - - `type: :shell` +#### Response - The type of the shell tool. Always `shell`. +```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 +} +``` - - `:shell` +## Domain Types - - `allowed_callers: Array[:direct | :programmatic]` +### Required Action Function Tool Call - The tool invocation context(s). +- `class RequiredActionFunctionToolCall` - - `:direct` + Tool call objects - - `:programmatic` + - `id: String` - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + 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. - - `class BetaContainerAuto` + - `function: Function{ arguments, name}` - - `type: :container_auto` + The function definition. - Automatically creates a container for this request + - `arguments: String` - - `:container_auto` + The arguments that the model expects you to pass to the function. - - `file_ids: Array[String]` + - `name: String` - An optional list of uploaded files to make available to your code. + The name of the function. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `type: :function` - The memory limit for the container. + The type of tool call the output is required for. For now, this is always `function`. - - `:"1g"` + - `:function` - - `:"4g"` +### Run - - `:"16g"` +- `class Run` - - `:"64g"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `id: String` - Network access policy for the container. + The identifier, which can be referenced in API endpoints. - - `class BetaContainerNetworkPolicyDisabled` + - `assistant_id: String` - - `class BetaContainerNetworkPolicyAllowlist` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `cancelled_at: Integer` - An optional list of skills referenced by id or inline data. + The Unix timestamp (in seconds) for when the run was cancelled. - - `class BetaSkillReference` + - `completed_at: Integer` - - `skill_id: String` + The Unix timestamp (in seconds) for when the run was completed. - The ID of the referenced skill. + - `created_at: Integer` - - `type: :skill_reference` + The Unix timestamp (in seconds) for when the run was created. - References a skill created with the /v1/skills endpoint. + - `expires_at: Integer` - - `:skill_reference` + The Unix timestamp (in seconds) for when the run will expire. - - `version: String` + - `failed_at: Integer` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The Unix timestamp (in seconds) for when the run failed. - - `class BetaInlineSkill` + - `incomplete_details: IncompleteDetails{ reason}` - - `description: String` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The description of the skill. + - `reason: :max_completion_tokens | :max_prompt_tokens` - - `name: 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 name of the skill. + - `:max_completion_tokens` - - `source: BetaInlineSkillSource` + - `:max_prompt_tokens` - Inline skill payload + - `instructions: String` - - `data: String` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Base64-encoded skill zip bundle. + - `last_error: LastError{ code, message}` - - `media_type: :"application/zip"` + The last error associated with this run. Will be `null` if there are no errors. - The media type of the inline skill payload. Must be `application/zip`. + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt` - - `:"application/zip"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `type: :base64` + - `:server_error` - The type of the inline skill source. Must be `base64`. + - `:rate_limit_exceeded` - - `:base64` + - `:invalid_prompt` - - `type: :inline` + - `message: String` - Defines an inline skill for this request. + A human-readable description of the error. - - `:inline` + - `max_completion_tokens: Integer` - - `class BetaLocalEnvironment` + The maximum number of completion tokens specified to have been used over the course of the run. - - `type: :local` + - `max_prompt_tokens: Integer` - Use a local computer environment. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `:local` + - `metadata: Metadata` - - `skills: Array[BetaLocalSkill]` + Set of 16 key-value pairs that can be attached to an object. 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 optional list of skills. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `description: String` + - `model: String` - The description of the skill. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `name: String` + - `object: :"thread.run"` - The name of the skill. + The object type, which is always `thread.run`. - - `path: String` + - `:"thread.run"` - The path to the directory containing the skill. + - `parallel_tool_calls: bool` - - `class BetaContainerReference` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `container_id: String` + - `required_action: RequiredAction{ submit_tool_outputs, type}` - The ID of the referenced container. + Details on the action required to continue the run. Will be `null` if no action is required. - - `type: :container_reference` + - `submit_tool_outputs: SubmitToolOutputs{ tool_calls}` - References a container created with the /v1/containers endpoint + Details on the tool outputs needed for this run to continue. - - `:container_reference` + - `tool_calls: Array[RequiredActionFunctionToolCall]` - - `class BetaCustomTool` + A list of the relevant 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) + - `id: String` - - `name: 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 name of the custom tool, used to identify it in tool calls. + - `function: Function{ arguments, name}` - - `type: :custom` + The function definition. - The type of the custom tool. Always `custom`. + - `arguments: String` - - `:custom` + The arguments that the model expects you to pass to the function. - - `allowed_callers: Array[:direct | :programmatic]` + - `name: String` - The tool invocation context(s). + The name of the function. - - `:direct` + - `type: :function` - - `:programmatic` + The type of tool call the output is required for. For now, this is always `function`. - - `defer_loading: bool` + - `:function` - Whether this tool should be deferred and discovered via tool search. + - `type: :submit_tool_outputs` - - `description: String` + For now, this is always `submit_tool_outputs`. - Optional description of the custom tool, used to provide more context. + - `:submit_tool_outputs` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + - `response_format: AssistantResponseFormatOption` - The input format for the custom tool. Default is unconstrained text. + 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`. - - `class 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](https://platform.openai.com/docs/guides/structured-outputs). - Unconstrained free-form text. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `type: :text` + **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. - Unconstrained text format. Always `text`. + - `AssistantResponseFormatOption = :auto` - - `:text` + `auto` is the default value - - `class Grammar` + - `:auto` - A grammar defined by the user. + - `class ResponseFormatText` - - `definition: String` + Default response format. Used to generate text responses. - The grammar definition. + - `type: :text` - - `syntax: :lark | :regex` + The type of response format being defined. Always `text`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `:text` - - `:lark` + - `class ResponseFormatJSONObject` - - `:regex` + 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: :grammar` + - `type: :json_object` - Grammar format. Always `grammar`. + The type of response format being defined. Always `json_object`. - - `:grammar` + - `:json_object` - - `class BetaNamespaceTool` + - `class ResponseFormatJSONSchema` - Groups function/custom tools under a shared namespace. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `description: String` + - `json_schema: JSONSchema{ name, description, schema, strict}` - A description of the namespace shown to the model. + Structured Outputs configuration options, including a JSON Schema. - `name: String` - The namespace name used in tool calls (for example, `crm`). + 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. - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `description: String` - The function/custom tools available inside this namespace. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class Function` + - `schema: Hash[Symbol, untyped]` - - `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/). - - `type: :function` + - `strict: bool` - - `: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](https://platform.openai.com/docs/guides/structured-outputs). - - `allowed_callers: Array[:direct | :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: Integer` - - `defer_loading: bool` + The Unix timestamp (in seconds) for when the run was started. - Whether this function should be deferred and discovered via tool search. + - `status: RunStatus` - - `description: String` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `output_schema: Hash[Symbol, untyped]` + - `:queued` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `:in_progress` - - `parameters: untyped` + - `:requires_action` - - `strict: bool` + - `:cancelling` - 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. + - `:cancelled` - - `class BetaCustomTool` + - `: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) + - `:completed` - - `type: :namespace` + - `:incomplete` - The type of the tool. Always `namespace`. + - `:expired` - - `:namespace` + - `thread_id: String` - - `class BetaToolSearchTool` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - Hosted or BYOT tool search configuration for deferred tools. + - `tool_choice: AssistantToolChoiceOption` - - `type: :tool_search` + 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 tool. Always `tool_search`. + - `Auto = :none | :auto | :required` - - `:tool_search` + `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. - - `description: String` + - `:none` - Description shown to the model for a client-executed tool search tool. + - `:auto` - - `execution: :server | :client` + - `:required` - Whether tool search is executed by the server or by the client. + - `class AssistantToolChoice` - - `:server` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `:client` + - `type: :function | :code_interpreter | :file_search` - - `parameters: untyped` + The type of the tool. If type is `function`, the function name must be set - Parameter schema for a client-executed tool search tool. + - `:function` - - `class BetaWebSearchPreviewTool` + - `: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). + - `:file_search` - - `type: :web_search_preview | :web_search_preview_2025_03_11` + - `function: AssistantToolChoiceFunction` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `name: String` - - `:web_search_preview` + The name of the function to call. - - `:web_search_preview_2025_03_11` + - `tools: Array[AssistantTool]` - - `search_content_types: Array[:text | :image]` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `:text` + - `class CodeInterpreterTool` - - `:image` + - `type: :code_interpreter` - - `search_context_size: :low | :medium | :high` + The type of tool being defined: `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. + - `:code_interpreter` - - `:low` + - `class FileSearchTool` - - `:medium` + - `type: :file_search` - - `:high` + The type of tool being defined: `file_search` - - `user_location: UserLocation{ type, city, country, 2 more}` + - `:file_search` - The user's location. + - `file_search: FileSearch{ max_num_results, ranking_options}` - - `type: :approximate` + Overrides for the file search tool. - The type of location approximation. Always `approximate`. + - `max_num_results: Integer` - - `:approximate` + 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. - - `city: 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. - Free text input for the city of the user, e.g. `San Francisco`. + - `ranking_options: RankingOptions{ score_threshold, ranker}` - - `country: 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 two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `region: String` + - `score_threshold: Float` - Free text input for the region of the user, e.g. `California`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `timezone: String` + - `ranker: :auto | :default_2024_08_21` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaApplyPatchTool` + - `:auto` - Allows the assistant to create, delete, or update files using unified diffs. + - `:default_2024_08_21` - - `type: :apply_patch` + - `class FunctionTool` - The type of the tool. Always `apply_patch`. + - `function: FunctionDefinition` - - `:apply_patch` + - `name: String` - - `allowed_callers: Array[:direct | :programmatic]` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The tool invocation context(s). + - `description: String` - - `:direct` + A description of what the function does, used by the model to choose when and how to call the function. - - `:programmatic` + - `parameters: FunctionParameters` - - `type: :tool_search_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. - The type of the item. Always `tool_search_output`. + Omitting `parameters` defines a function with an empty parameter list. - - `:tool_search_output` + - `strict: bool` - - `agent: Agent{ 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](https://platform.openai.com/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: String` + - `truncation_strategy: TruncationStrategy{ type, last_messages}` - The identifier of the actor that created the item. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `class AdditionalTools` + - `type: :auto | :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 additional tools item. + - `:auto` - - `role: :unknown | :user | :assistant | 5 more` + - `:last_messages` - The role that provided the additional tools. + - `last_messages: Integer` - - `:unknown` + The number of most recent messages from the thread when constructing the context for the run. - - `:user` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - - `:assistant` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `:system` + - `completion_tokens: Integer` - - `:critic` + Number of completion tokens used over the course of the run. - - `:discriminator` + - `prompt_tokens: Integer` - - `:developer` + Number of prompt tokens used over the course of the run. - - `:tool` + - `total_tokens: Integer` - - `tools: Array[BetaTool]` + Total number of tokens used (prompt + completion). - The additional tool definitions made available at this item. + - `temperature: Float` - - `class BetaFunctionTool` + The sampling temperature used for this run. If not set, defaults to 1. - 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). + - `top_p: Float` - - `class BetaFileSearchTool` + The nucleus sampling value used for this run. If not set, defaults to 1. - 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). +### Run Status - - `class BetaComputerTool` +- `RunStatus = :queued | :in_progress | :requires_action | 6 more` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `class BetaComputerUsePreviewTool` + - `:queued` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `:in_progress` - - `class BetaWebSearchTool` + - `:requires_action` - 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). + - `:cancelling` - - `class Mcp` + - `:cancelled` - 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). + - `:failed` - - `class CodeInterpreter` + - `:completed` - A tool that runs Python code to help generate a response to a prompt. + - `:incomplete` - - `class ProgrammaticToolCalling` + - `:expired` - - `class ImageGeneration` +# Steps - A tool that generates images using the GPT image models. +## List run steps - - `class LocalShell` +`beta.threads.runs.steps.list(run_id, **kwargs) -> CursorPage` - A tool that allows the model to execute shell commands in a local environment. +**get** `/threads/{thread_id}/runs/{run_id}/steps` - - `class BetaFunctionShellTool` +Returns a list of run steps belonging to a run. - A tool that allows the model to execute shell commands. +### Parameters - - `class BetaCustomTool` +- `thread_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) +- `run_id: String` - - `class BetaNamespaceTool` +- `after: String` - Groups function/custom tools under a shared namespace. + 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. - - `class BetaToolSearchTool` +- `before: String` - Hosted or BYOT tool search configuration for deferred 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. - - `class BetaWebSearchPreviewTool` +- `include: Array[RunStepInclude]` - 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 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. - - `class BetaApplyPatchTool` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Allows the assistant to create, delete, or update files using unified diffs. + - `:"step_details.tool_calls[*].file_search.results[*].content"` - - `type: :additional_tools` +- `limit: Integer` - The type of the item. Always `additional_tools`. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `:additional_tools` +- `order: :asc | :desc` - - `agent: Agent{ agent_name}` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - The agent that produced this item. + - `:asc` - - `agent_name: String` + - `:desc` - The canonical name of the agent that produced this item. +### Returns - - `class BetaResponseReasoningItem` +- `class RunStep` - 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). + Represents a step in execution of a run. - `id: String` - The unique identifier of the reasoning content. - - - `summary: Array[Summary{ text, type}]` - - Reasoning summary content. + The identifier of the run step, which can be referenced in API endpoints. - - `text: String` + - `assistant_id: String` - A summary of the reasoning output from the model so far. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `type: :summary_text` + - `cancelled_at: Integer` - The type of the object. Always `summary_text`. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `:summary_text` + - `completed_at: Integer` - - `type: :reasoning` + The Unix timestamp (in seconds) for when the run step completed. - The type of the object. Always `reasoning`. + - `created_at: Integer` - - `:reasoning` + The Unix timestamp (in seconds) for when the run step was created. - - `agent: Agent{ agent_name}` + - `expired_at: Integer` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `agent_name: String` + - `failed_at: Integer` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run step failed. - - `content: Array[Content{ text, type}]` + - `last_error: LastError{ code, message}` - Reasoning text content. + The last error associated with this run step. Will be `null` if there are no errors. - - `text: String` + - `code: :server_error | :rate_limit_exceeded` - The reasoning text from the model. + One of `server_error` or `rate_limit_exceeded`. - - `type: :reasoning_text` + - `:server_error` - The type of the reasoning text. Always `reasoning_text`. + - `:rate_limit_exceeded` - - `:reasoning_text` + - `message: String` - - `encrypted_content: String` + A human-readable description of the error. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `metadata: Metadata` - - `status: :in_progress | :completed | :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. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `:in_progress` + - `object: :"thread.run.step"` - - `:completed` + The object type, which is always `thread.run.step`. - - `:incomplete` + - `:"thread.run.step"` - - `class Program` + - `run_id: String` - - `id: String` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - The unique ID of the program item. + - `status: :in_progress | :cancelled | :failed | 2 more` - - `call_id: String` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The stable call ID of the program item. + - `:in_progress` - - `code: String` + - `:cancelled` - The JavaScript source executed by programmatic tool calling. + - `:failed` - - `fingerprint: String` + - `:completed` - Opaque program replay fingerprint that must be round-tripped. + - `:expired` - - `type: :program` + - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` - The type of the item. Always `program`. + The details of the run step. - - `:program` + - `class MessageCreationStepDetails` - - `agent: Agent{ agent_name}` + Details of the message creation by the run step. - The agent that produced this item. + - `message_creation: MessageCreation{ message_id}` - - `agent_name: String` + - `message_id: String` - The canonical name of the agent that produced this item. + The ID of the message that was created by this run step. - - `class ProgramOutput` + - `type: :message_creation` - - `id: String` + Always `message_creation`. - The unique ID of the program output item. + - `:message_creation` - - `call_id: String` + - `class ToolCallsStepDetails` - The call ID of the program item. + Details of the tool call. - - `result: String` + - `tool_calls: Array[ToolCall]` - The result produced by the program 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`. - - `status: :completed | :incomplete` + - `class CodeInterpreterToolCall` - The terminal status of the program output item. + Details of the Code Interpreter tool call the run step was involved in. - - `:completed` + - `id: String` - - `:incomplete` + The ID of the tool call. - - `type: :program_output` + - `code_interpreter: CodeInterpreter{ input, outputs}` - The type of the item. Always `program_output`. + The Code Interpreter tool call definition. - - `:program_output` + - `input: String` - - `agent: Agent{ agent_name}` + The input to the Code Interpreter tool call. - The agent that produced this item. + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - - `agent_name: 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 canonical name of the agent that produced this item. + - `class Logs` - - `class BetaResponseCompactionItem` + Text output from the Code Interpreter tool call as part of a run step. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `logs: String` - - `id: String` + The text output from the Code Interpreter tool call. - The unique ID of the compaction item. + - `type: :logs` - - `encrypted_content: String` + Always `logs`. - The encrypted content that was produced by compaction. + - `:logs` - - `type: :compaction` + - `class Image` - The type of the item. Always `compaction`. + - `image: Image{ file_id}` - - `:compaction` + - `file_id: String` - - `agent: Agent{ agent_name}` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The agent that produced this item. + - `type: :image` - - `agent_name: String` + Always `image`. - The canonical name of the agent that produced this item. + - `:image` - - `created_by: String` + - `type: :code_interpreter` - The identifier of the actor that created the item. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class ImageGenerationCall` + - `:code_interpreter` - An image generation request made by the model. + - `class FileSearchToolCall` - `id: String` - The unique ID of the image generation call. + The ID of the tool call object. - - `result: String` + - `file_search: FileSearch{ ranking_options, results}` - The generated image encoded in base64. + For now, this is always going to be an empty object. - - `status: :in_progress | :completed | :generating | :failed` + - `ranking_options: RankingOptions{ ranker, score_threshold}` - The status of the image generation call. + The ranking options for the file search. - - `:in_progress` + - `ranker: :auto | :default_2024_08_21` - - `:completed` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `:generating` + - `:auto` - - `:failed` + - `:default_2024_08_21` - - `type: :image_generation_call` + - `score_threshold: Float` - The type of the image generation call. Always `image_generation_call`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `:image_generation_call` + - `results: Array[Result{ file_id, file_name, score, content}]` - - `agent: Agent{ agent_name}` + The results of the file search. - The agent that produced this item. + - `file_id: String` - - `agent_name: String` + The ID of the file that result was found in. - The canonical name of the agent that produced this item. + - `file_name: String` - - `class BetaResponseCodeInterpreterToolCall` + The name of the file that result was found in. - A tool call to run code. + - `score: Float` - - `id: String` + The score of the result. All values must be a floating point number between 0 and 1. - The unique ID of the code interpreter tool call. + - `content: Array[Content{ text, type}]` - - `code: String` + The content of the result that was found. The content is only included if requested via the include query parameter. - The code to run, or null if not available. + - `text: String` - - `container_id: String` + The text content of the file. - The ID of the container used to run the code. + - `type: :text` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + The type of the content. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `:text` - - `class Logs` + - `type: :file_search` - The logs output from the code interpreter. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `logs: String` + - `:file_search` - The logs output from the code interpreter. + - `class FunctionToolCall` - - `type: :logs` + - `id: String` - The type of the output. Always `logs`. + The ID of the tool call object. - - `:logs` + - `function: Function{ arguments, name, output}` - - `class Image` + The definition of the function that was called. - The image output from the code interpreter. + - `arguments: String` - - `type: :image` + The arguments passed to the function. - The type of the output. Always `image`. + - `name: String` - - `:image` + The name of the function. - - `url: String` + - `output: String` - The URL of the image output from the code interpreter. + 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. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `type: :function` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `:in_progress` + - `:function` - - `:completed` + - `type: :tool_calls` - - `:incomplete` + Always `tool_calls`. - - `:interpreting` + - `:tool_calls` - - `:failed` + - `thread_id: String` - - `type: :code_interpreter_call` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `type: :message_creation | :tool_calls` - - `:code_interpreter_call` + The type of run step, which can be either `message_creation` or `tool_calls`. - - `agent: Agent{ agent_name}` + - `:message_creation` - The agent that produced this item. + - `:tool_calls` - - `agent_name: String` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - The canonical name of the agent that produced this item. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `class LocalShellCall` + - `completion_tokens: Integer` - A tool call to run a command on the local shell. + Number of completion tokens used over the course of the run step. - - `id: String` + - `prompt_tokens: Integer` - The unique ID of the local shell call. + Number of prompt tokens used over the course of the run step. - - `action: Action{ command, env, type, 3 more}` + - `total_tokens: Integer` - Execute a shell command on the server. + Total number of tokens used (prompt + completion). - - `command: Array[String]` +### Example - The command to run. +```ruby +require "openai" - - `env: Hash[Symbol, String]` +openai = OpenAI::Client.new(api_key: "My API Key") - Environment variables to set for the command. +page = openai.beta.threads.runs.steps.list("run_id", thread_id: "thread_id") - - `type: :exec` +puts(page) +``` - The type of the local shell action. Always `exec`. +#### Response - - `:exec` +```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" +} +``` - - `timeout_ms: Integer` +## Retrieve run step - Optional timeout in milliseconds for the command. +`beta.threads.runs.steps.retrieve(step_id, **kwargs) -> RunStep` - - `user: String` +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - Optional user to run the command as. +Retrieves a run step. - - `working_directory: String` +### Parameters - Optional working directory to run the command in. +- `thread_id: String` - - `call_id: String` +- `run_id: String` - The unique ID of the local shell tool call generated by the model. +- `step_id: String` - - `status: :in_progress | :completed | :incomplete` +- `include: Array[RunStepInclude]` - The status of the local shell call. + 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. - - `:in_progress` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `:completed` + - `:"step_details.tool_calls[*].file_search.results[*].content"` - - `:incomplete` +### Returns - - `type: :local_shell_call` +- `class RunStep` - The type of the local shell call. Always `local_shell_call`. + Represents a step in execution of a run. - - `:local_shell_call` + - `id: String` - - `agent: Agent{ agent_name}` + The identifier of the run step, which can be referenced in API endpoints. - The agent that produced this item. + - `assistant_id: String` - - `agent_name: String` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The canonical name of the agent that produced this item. + - `cancelled_at: Integer` - - `class LocalShellCallOutput` + The Unix timestamp (in seconds) for when the run step was cancelled. - The output of a local shell tool call. + - `completed_at: Integer` - - `id: String` + The Unix timestamp (in seconds) for when the run step completed. - The unique ID of the local shell tool call generated by the model. + - `created_at: Integer` - - `output: String` + The Unix timestamp (in seconds) for when the run step was created. - A JSON string of the output of the local shell tool call. + - `expired_at: Integer` - - `type: :local_shell_call_output` + 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 local shell tool call output. Always `local_shell_call_output`. + - `failed_at: Integer` - - `:local_shell_call_output` + The Unix timestamp (in seconds) for when the run step failed. - - `agent: Agent{ agent_name}` + - `last_error: LastError{ code, message}` - The agent that produced this item. + The last error associated with this run step. Will be `null` if there are no errors. - - `agent_name: String` + - `code: :server_error | :rate_limit_exceeded` - The canonical name of the agent that produced this item. + One of `server_error` or `rate_limit_exceeded`. - - `status: :in_progress | :completed | :incomplete` + - `:server_error` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `:rate_limit_exceeded` - - `:in_progress` + - `message: String` - - `:completed` + A human-readable description of the error. - - `:incomplete` + - `metadata: Metadata` - - `class BetaResponseFunctionShellToolCall` + Set of 16 key-value pairs that can be attached to an object. 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 tool call that executes one or more shell commands in a managed environment. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: String` + - `object: :"thread.run.step"` - The unique ID of the shell tool call. Populated when this item is returned via API. + The object type, which is always `thread.run.step`. - - `action: Action{ commands, max_output_length, timeout_ms}` + - `:"thread.run.step"` - The shell commands and limits that describe how to run the tool call. + - `run_id: String` - - `commands: Array[String]` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `max_output_length: Integer` + - `status: :in_progress | :cancelled | :failed | 2 more` - Optional maximum number of characters to return from each command. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `timeout_ms: Integer` + - `:in_progress` - Optional timeout in milliseconds for the commands. + - `:cancelled` - - `call_id: String` + - `:failed` - The unique ID of the shell tool call generated by the model. + - `:completed` - - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + - `:expired` - Represents the use of a local environment to perform shell actions. + - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` - - `class BetaResponseLocalEnvironment` + The details of the run step. - Represents the use of a local environment to perform shell actions. + - `class MessageCreationStepDetails` - - `type: :local` + Details of the message creation by the run step. - The environment type. Always `local`. + - `message_creation: MessageCreation{ message_id}` - - `:local` + - `message_id: String` - - `class BetaResponseContainerReference` + The ID of the message that was created by this run step. - Represents a container created with /v1/containers. + - `type: :message_creation` - - `container_id: String` + Always `message_creation`. - - `type: :container_reference` + - `:message_creation` - The environment type. Always `container_reference`. + - `class ToolCallsStepDetails` - - `:container_reference` + Details of the tool call. - - `status: :in_progress | :completed | :incomplete` + - `tool_calls: Array[ToolCall]` - The status of the shell call. One of `in_progress`, `completed`, or `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`. - - `:in_progress` + - `class CodeInterpreterToolCall` - - `:completed` + Details of the Code Interpreter tool call the run step was involved in. - - `:incomplete` + - `id: String` - - `type: :shell_call` + The ID of the tool call. - The type of the item. Always `shell_call`. + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `:shell_call` + The Code Interpreter tool call definition. - - `agent: Agent{ agent_name}` + - `input: String` - The agent that produced this item. + The input to the Code Interpreter tool call. - - `agent_name: String` + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - The canonical name of the agent that produced this item. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `class Logs` - The execution context that produced this tool call. + Text output from the Code Interpreter tool call as part of a run step. - - `class Direct` + - `logs: String` - - `type: :direct` + The text output from the Code Interpreter tool call. - - `:direct` + - `type: :logs` - - `class Program` + Always `logs`. - - `caller_id: String` + - `:logs` - The call ID of the program item that produced this tool call. + - `class Image` - - `type: :program` + - `image: Image{ file_id}` - - `:program` + - `file_id: String` - - `created_by: String` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The ID of the entity that created this tool call. + - `type: :image` - - `class BetaResponseFunctionShellToolCallOutput` + Always `image`. - The output of a shell tool call that was emitted. + - `:image` - - `id: String` + - `type: :code_interpreter` - 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 `code_interpreter` for this type of tool call. - - `call_id: String` + - `:code_interpreter` - The unique ID of the shell tool call generated by the model. + - `class FileSearchToolCall` - - `max_output_length: Integer` + - `id: String` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The ID of the tool call object. - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + - `file_search: FileSearch{ ranking_options, results}` - An array of shell call output contents + For now, this is always going to be an empty object. - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `ranking_options: RankingOptions{ ranker, score_threshold}` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The ranking options for the file search. - - `class Timeout` + - `ranker: :auto | :default_2024_08_21` - Indicates that the shell call exceeded its configured time limit. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: :timeout` + - `:auto` - The outcome type. Always `timeout`. + - `:default_2024_08_21` - - `:timeout` + - `score_threshold: Float` - - `class Exit` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Indicates that the shell commands finished and returned an exit code. + - `results: Array[Result{ file_id, file_name, score, content}]` - - `exit_code: Integer` + The results of the file search. - Exit code from the shell process. + - `file_id: String` - - `type: :exit` + The ID of the file that result was found in. - The outcome type. Always `exit`. + - `file_name: String` - - `:exit` + The name of the file that result was found in. - - `stderr: String` + - `score: Float` - The standard error output that was captured. + The score of the result. All values must be a floating point number between 0 and 1. - - `stdout: String` + - `content: Array[Content{ text, type}]` - The standard output that was captured. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `created_by: String` + - `text: String` - The identifier of the actor that created the item. + The text content of the file. - - `status: :in_progress | :completed | :incomplete` + - `type: :text` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The type of the content. - - `:in_progress` + - `:text` - - `:completed` + - `type: :file_search` - - `:incomplete` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: :shell_call_output` + - `:file_search` - The type of the shell call output. Always `shell_call_output`. + - `class FunctionToolCall` - - `:shell_call_output` + - `id: String` - - `agent: Agent{ agent_name}` + The ID of the tool call object. - The agent that produced this item. + - `function: Function{ arguments, name, output}` - - `agent_name: String` + The definition of the function that was called. - The canonical name of the agent that produced this item. + - `arguments: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The arguments passed to the function. - The execution context that produced this tool call. + - `name: String` - - `class Direct` + The name of the function. - - `type: :direct` + - `output: String` - - `:direct` + 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. - - `class Program` + - `type: :function` - - `caller_id: String` + The type of tool call. This is always going to be `function` for this type of tool call. - The call ID of the program item that produced this tool call. + - `:function` - - `type: :program` + - `type: :tool_calls` - - `:program` + Always `tool_calls`. - - `created_by: String` + - `:tool_calls` - The identifier of the actor that created the item. + - `thread_id: String` - - `class BetaResponseApplyPatchToolCall` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - A tool call that applies file diffs by creating, deleting, or updating files. + - `type: :message_creation | :tool_calls` - - `id: String` + The type of run step, which can be either `message_creation` or `tool_calls`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `:message_creation` - - `call_id: String` + - `:tool_calls` - The unique ID of the apply patch tool call generated by the model. + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `completion_tokens: Integer` - - `class CreateFile` + Number of completion tokens used over the course of the run step. - Instruction describing how to create a file via the apply_patch tool. + - `prompt_tokens: Integer` - - `diff: String` + Number of prompt tokens used over the course of the run step. - Diff to apply. + - `total_tokens: Integer` - - `path: String` + Total number of tokens used (prompt + completion). - Path of the file to create. +### Example - - `type: :create_file` +```ruby +require "openai" - Create a new file with the provided diff. +openai = OpenAI::Client.new(api_key: "My API Key") - - `:create_file` +run_step = openai.beta.threads.runs.steps.retrieve("step_id", thread_id: "thread_id", run_id: "run_id") - - `class DeleteFile` +puts(run_step) +``` - Instruction describing how to delete a file via the apply_patch tool. +#### Response - - `path: String` +```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 + } +} +``` - Path of the file to delete. +## Domain Types - - `type: :delete_file` +### Code Interpreter Logs - Delete the specified file. +- `class CodeInterpreterLogs` - - `:delete_file` + Text output from the Code Interpreter tool call as part of a run step. - - `class UpdateFile` + - `index: Integer` - Instruction describing how to update a file via the apply_patch tool. + The index of the output in the outputs array. - - `diff: String` + - `type: :logs` - Diff to apply. + Always `logs`. - - `path: String` + - `:logs` - Path of the file to update. + - `logs: String` - - `type: :update_file` + The text output from the Code Interpreter tool call. - Update an existing file with the provided diff. +### Code Interpreter Output Image - - `:update_file` +- `class CodeInterpreterOutputImage` - - `status: :in_progress | :completed` + - `index: Integer` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The index of the output in the outputs array. - - `:in_progress` + - `type: :image` - - `:completed` + Always `image`. - - `type: :apply_patch_call` + - `:image` - The type of the item. Always `apply_patch_call`. + - `image: Image{ file_id}` - - `:apply_patch_call` + - `file_id: String` - - `agent: Agent{ agent_name}` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The agent that produced this item. +### Code Interpreter Tool Call - - `agent_name: String` +- `class CodeInterpreterToolCall` - The canonical name of the agent that produced this item. + Details of the Code Interpreter tool call the run step was involved in. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `id: String` - The execution context that produced this tool call. + The ID of the tool call. - - `class Direct` + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `type: :direct` + The Code Interpreter tool call definition. - - `:direct` + - `input: String` - - `class Program` + The input to the Code Interpreter tool call. - - `caller_id: String` + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - The call ID of the program item that produced this 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. - - `type: :program` + - `class Logs` - - `:program` + Text output from the Code Interpreter tool call as part of a run step. - - `created_by: String` + - `logs: String` - The ID of the entity that created this tool call. + The text output from the Code Interpreter tool call. - - `class BetaResponseApplyPatchToolCallOutput` + - `type: :logs` - The output emitted by an apply patch tool call. + Always `logs`. - - `id: String` + - `:logs` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `class Image` - - `call_id: String` + - `image: Image{ file_id}` - The unique ID of the apply patch tool call generated by the model. + - `file_id: String` - - `status: :completed | :failed` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `type: :image` - - `:completed` + Always `image`. - - `:failed` + - `:image` - - `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: Agent{ agent_name}` +### Code Interpreter Tool Call Delta - The agent that produced this item. +- `class CodeInterpreterToolCallDelta` - - `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. + - `index: Integer` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The index of the tool call in the tool calls array. - The execution context that produced this tool call. + - `type: :code_interpreter` - - `class Direct` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `type: :direct` + - `:code_interpreter` - - `:direct` + - `id: String` - - `class Program` + The ID of the tool call. - - `caller_id: String` + - `code_interpreter: CodeInterpreter{ input, outputs}` - The call ID of the program item that produced this tool call. + The Code Interpreter tool call definition. - - `type: :program` + - `input: String` - - `:program` + The input to the Code Interpreter tool call. - - `created_by: String` + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - The ID of the entity that created this tool call output. + 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. - - `output: String` + - `class CodeInterpreterLogs` - Optional textual output returned by the apply patch tool. + Text output from the Code Interpreter tool call as part of a run step. - - `class McpListTools` + - `index: Integer` - A list of tools available on an MCP server. + The index of the output in the outputs array. - - `id: String` + - `type: :logs` - The unique ID of the list. + Always `logs`. - - `server_label: String` + - `:logs` - The label of the MCP server. + - `logs: String` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + The text output from the Code Interpreter tool call. - The tools available on the server. + - `class CodeInterpreterOutputImage` - - `input_schema: untyped` + - `index: Integer` - The JSON schema describing the tool's input. + The index of the output in the outputs array. - - `name: String` + - `type: :image` - The name of the tool. + Always `image`. - - `annotations: untyped` + - `:image` - Additional annotations about the tool. + - `image: Image{ file_id}` - - `description: String` + - `file_id: String` - The description of the tool. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `type: :mcp_list_tools` +### File Search Tool Call - The type of the item. Always `mcp_list_tools`. +- `class FileSearchToolCall` - - `:mcp_list_tools` + - `id: String` - - `agent: Agent{ agent_name}` + The ID of the tool call object. - The agent that produced this item. + - `file_search: FileSearch{ ranking_options, results}` - - `agent_name: String` + For now, this is always going to be an empty object. - The canonical name of the agent that produced this item. + - `ranking_options: RankingOptions{ ranker, score_threshold}` - - `error: String` + The ranking options for the file search. - Error message if the server could not list tools. + - `ranker: :auto | :default_2024_08_21` - - `class McpApprovalRequest` + The ranker to use for the file search. If not specified will use the `auto` ranker. - A request for human approval of a tool invocation. + - `:auto` - - `id: String` + - `:default_2024_08_21` - The unique ID of the approval request. + - `score_threshold: Float` - - `arguments: String` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A JSON string of arguments for the tool. + - `results: Array[Result{ file_id, file_name, score, content}]` - - `name: String` + The results of the file search. - The name of the tool to run. + - `file_id: String` - - `server_label: String` + The ID of the file that result was found in. - The label of the MCP server making the request. + - `file_name: String` - - `type: :mcp_approval_request` + The name of the file that result was found in. - The type of the item. Always `mcp_approval_request`. + - `score: Float` - - `:mcp_approval_request` + The score of the result. All values must be a floating point number between 0 and 1. - - `agent: Agent{ agent_name}` + - `content: Array[Content{ text, type}]` - The agent that produced this item. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `agent_name: String` + - `text: String` - The canonical name of the agent that produced this item. + The text content of the file. - - `class McpApprovalResponse` + - `type: :text` - A response to an MCP approval request. + The type of the content. - - `id: String` + - `:text` - The unique ID of the approval response + - `type: :file_search` - - `approval_request_id: String` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The ID of the approval request being answered. + - `:file_search` - - `approve: bool` +### File Search Tool Call Delta - Whether the request was approved. +- `class FileSearchToolCallDelta` - - `type: :mcp_approval_response` + - `file_search: untyped` - The type of the item. Always `mcp_approval_response`. + For now, this is always going to be an empty object. - - `:mcp_approval_response` + - `index: Integer` - - `agent: Agent{ agent_name}` + The index of the tool call in the tool calls array. - The agent that produced this item. + - `type: :file_search` - - `agent_name: String` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The canonical name of the agent that produced this item. + - `:file_search` - - `reason: String` + - `id: String` - Optional reason for the decision. + The ID of the tool call object. - - `class McpCall` +### Function Tool Call - An invocation of a tool on an MCP server. +- `class FunctionToolCall` - `id: String` - The unique ID of the tool call. + The ID of the tool call object. + + - `function: Function{ arguments, name, output}` + + The definition of the function that was called. - `arguments: String` - A JSON string of the arguments passed to the tool. + The arguments passed to the function. - `name: String` - The name of the tool that was run. - - - `server_label: String` + The name of the function. - The label of the MCP server running the tool. + - `output: String` - - `type: :mcp_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. - The type of the item. Always `mcp_call`. + - `type: :function` - - `:mcp_call` + The type of tool call. This is always going to be `function` for this type of tool call. - - `agent: Agent{ agent_name}` + - `:function` - The agent that produced this item. +### Function Tool Call Delta - - `agent_name: String` +- `class FunctionToolCallDelta` - The canonical name of the agent that produced this item. + - `index: Integer` - - `approval_request_id: String` + The index of the tool call in the tool calls array. - 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: :function` - - `error: String` + The type of tool call. This is always going to be `function` for this type of tool call. - The error from the tool call, if any. + - `:function` - - `output: String` + - `id: String` - The output from the tool call. + The ID of the tool call object. - - `status: :in_progress | :completed | :incomplete | 2 more` + - `function: Function{ arguments, name, output}` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The definition of the function that was called. - - `:in_progress` + - `arguments: String` - - `:completed` + The arguments passed to the function. - - `:incomplete` + - `name: String` - - `:calling` + The name of the function. - - `:failed` + - `output: String` - - `class BetaResponseCustomToolCallItem` + 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. - A call to a custom tool created by the model. +### Message Creation Step Details - - `id: String` +- `class MessageCreationStepDetails` - The unique ID of the custom tool call item. + Details of the message creation by the run step. - - `status: :in_progress | :completed | :incomplete` + - `message_creation: MessageCreation{ message_id}` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `message_id: String` - - `:in_progress` + The ID of the message that was created by this run step. - - `:completed` + - `type: :message_creation` - - `:incomplete` + Always `message_creation`. - - `created_by: String` + - `:message_creation` - The identifier of the actor that created the item. +### Run Step - - `class BetaResponseCustomToolCallOutputItem` +- `class RunStep` - The output of a custom tool call from your code, being sent back to the model. + Represents a step in execution of a run. - `id: String` - The unique ID of the custom tool call output item. - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The identifier of the run step, which can be referenced in API endpoints. - - `:in_progress` + - `assistant_id: String` - - `:completed` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `:incomplete` + - `cancelled_at: Integer` - - `created_by: String` + The Unix timestamp (in seconds) for when the run step was cancelled. - The identifier of the actor that created the item. + - `completed_at: Integer` - - `first_id: String` + The Unix timestamp (in seconds) for when the run step completed. - The ID of the first item in the list. + - `created_at: Integer` - - `has_more: bool` + The Unix timestamp (in seconds) for when the run step was created. - Whether there are more items available. + - `expired_at: Integer` - - `last_id: String` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The ID of the last item in the list. + - `failed_at: Integer` - - `object: :list` + The Unix timestamp (in seconds) for when the run step failed. - The type of object returned, must be `list`. + - `last_error: LastError{ code, message}` - - `:list` + The last error associated with this run step. Will be `null` if there are no errors. -# Input Tokens + - `code: :server_error | :rate_limit_exceeded` -## Get input token counts + One of `server_error` or `rate_limit_exceeded`. -`beta.responses.input_tokens.count(**kwargs) -> InputTokenCountResponse` + - `:server_error` -**post** `/responses/input_tokens?beta=true` + - `:rate_limit_exceeded` -Get input token counts + - `message: String` -### Parameters + A human-readable description of the error. -- `conversation: String | BetaResponseConversationParam` + - `metadata: Metadata` - 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. + Set of 16 key-value pairs that can be attached to an object. 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 = 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 conversation. + - `object: :"thread.run.step"` - - `class BetaResponseConversationParam` + The object type, which is always `thread.run.step`. - The conversation that this response belongs to. + - `:"thread.run.step"` - - `id: String` + - `run_id: String` - The unique ID of the conversation. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. -- `input: String | Array[BetaResponseInputItem]` + - `status: :in_progress | :cancelled | :failed | 2 more` - Text, image, or file inputs to the model, used to generate a response + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `String = String` + - `:in_progress` - A text input to the model, equivalent to a text input with the `user` role. + - `:cancelled` - - `UnionMember1 = Array[BetaResponseInputItem]` + - `:failed` - A list of one or many input items to the model, containing different content types. + - `:completed` - - `class BetaEasyInputMessage` + - `:expired` - 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. + - `step_details: MessageCreationStepDetails | ToolCallsStepDetails` - - `content: String | BetaResponseInputMessageContentList` + The details of the run step. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `class MessageCreationStepDetails` - - `String = String` + Details of the message creation by the run step. - A text input to the model. + - `message_creation: MessageCreation{ message_id}` - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + - `message_id: String` - A list of one or many input items to the model, containing different content - types. + The ID of the message that was created by this run step. - - `class BetaResponseInputText` + - `type: :message_creation` - A text input to the model. + Always `message_creation`. - - `text: String` + - `:message_creation` - The text input to the model. + - `class ToolCallsStepDetails` - - `type: :input_text` + Details of the tool call. - The type of the input item. Always `input_text`. + - `tool_calls: Array[ToolCall]` - - `:input_text` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class CodeInterpreterToolCall` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Details of the Code Interpreter tool call the run step was involved in. - - `mode: :explicit` + - `id: String` - The breakpoint mode. Always `explicit`. + The ID of the tool call. - - `:explicit` + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `class BetaResponseInputImage` + The Code Interpreter tool call definition. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `input: String` - - `detail: :low | :high | :auto | :original` + The input to the Code Interpreter tool call. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - - `:low` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `:high` + - `class Logs` - - `:auto` + Text output from the Code Interpreter tool call as part of a run step. - - `:original` + - `logs: String` - - `type: :input_image` + The text output from the Code Interpreter tool call. - The type of the input item. Always `input_image`. + - `type: :logs` - - `:input_image` + Always `logs`. - - `file_id: String` + - `:logs` - The ID of the file to be sent to the model. + - `class Image` - - `image_url: String` + - `image: Image{ file_id}` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `file_id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the 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: :image` - - `mode: :explicit` + Always `image`. - The breakpoint mode. Always `explicit`. + - `:image` - - `:explicit` + - `type: :code_interpreter` - - `class BetaResponseInputFile` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A file input to the model. + - `:code_interpreter` - - `type: :input_file` + - `class FileSearchToolCall` - The type of the input item. Always `input_file`. + - `id: String` - - `:input_file` + The ID of the tool call object. - - `detail: :auto | :low | :high` + - `file_search: FileSearch{ ranking_options, results}` - 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`. + For now, this is always going to be an empty object. - - `:auto` + - `ranking_options: RankingOptions{ ranker, score_threshold}` - - `:low` + The ranking options for the file search. - - `:high` + - `ranker: :auto | :default_2024_08_21` - - `file_data: String` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The content of the file to be sent to the model. + - `:auto` - - `file_id: String` + - `:default_2024_08_21` - The ID of the file to be sent to the model. + - `score_threshold: Float` - - `file_url: String` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The URL of the file to be sent to the model. + - `results: Array[Result{ file_id, file_name, score, content}]` - - `filename: String` + The results of the file search. - The name of the file to be sent to the model. + - `file_id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The ID of the file that result was found 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. + - `file_name: String` - - `mode: :explicit` + The name of the file that result was found in. - The breakpoint mode. Always `explicit`. + - `score: Float` - - `:explicit` + The score of the result. All values must be a floating point number between 0 and 1. - - `role: :user | :assistant | :system | :developer` + - `content: Array[Content{ text, type}]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `:user` + - `text: String` - - `:assistant` + The text content of the file. - - `:system` + - `type: :text` - - `:developer` + The type of the content. - - `phase: :commentary` + - `:text` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: :file_search` - - `:commentary` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: :message` + - `:file_search` - The type of the message input. Always `message`. + - `class FunctionToolCall` - - `:message` + - `id: String` - - `class Message` + The ID of the tool call object. - 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. + - `function: Function{ arguments, name, output}` - - `content: BetaResponseInputMessageContentList` + The definition of the function that was called. - A list of one or many input items to the model, containing different content - types. + - `arguments: String` - - `role: :user | :system | :developer` + The arguments passed to the function. - The role of the message input. One of `user`, `system`, or `developer`. + - `name: String` - - `:user` + The name of the function. - - `:system` + - `output: String` - - `:developer` + 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. - - `agent: Agent{ agent_name}` + - `type: :function` - The agent that produced this item. + The type of tool call. This is always going to be `function` for this type of tool call. - - `agent_name: String` + - `:function` - The canonical name of the agent that produced this item. + - `type: :tool_calls` - - `status: :in_progress | :completed | :incomplete` + Always `tool_calls`. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `:tool_calls` - - `:in_progress` + - `thread_id: String` - - `:completed` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `:incomplete` + - `type: :message_creation | :tool_calls` - - `type: :message` + The type of run step, which can be either `message_creation` or `tool_calls`. - The type of the message input. Always set to `message`. + - `:message_creation` - - `:message` + - `:tool_calls` - - `class BetaResponseOutputMessage` + - `usage: Usage{ completion_tokens, prompt_tokens, total_tokens}` - An output message from the model. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `id: String` + - `completion_tokens: Integer` - The unique ID of the output message. + Number of completion tokens used over the course of the run step. - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + - `prompt_tokens: Integer` - The content of the output message. + Number of prompt tokens used over the course of the run step. - - `class BetaResponseOutputText` + - `total_tokens: Integer` - A text output from the model. + Total number of tokens used (prompt + completion). - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` +### Run Step Delta - The annotations of the text output. +- `class RunStepDelta` - - `class FileCitation` + The delta containing the fields that have changed on the run step. - A citation to a file. + - `step_details: RunStepDeltaMessageDelta | ToolCallDeltaObject` - - `file_id: String` + The details of the run step. - The ID of the file. + - `class RunStepDeltaMessageDelta` - - `filename: String` + Details of the message creation by the run step. - The filename of the file cited. + - `type: :message_creation` - - `index: Integer` + Always `message_creation`. - The index of the file in the list of files. + - `:message_creation` - - `type: :file_citation` + - `message_creation: MessageCreation{ message_id}` - The type of the file citation. Always `file_citation`. + - `message_id: String` - - `:file_citation` + The ID of the message that was created by this run step. - - `class URLCitation` + - `class ToolCallDeltaObject` - A citation for a web resource used to generate a model response. + Details of the tool call. - - `end_index: Integer` + - `type: :tool_calls` - The index of the last character of the URL citation in the message. + Always `tool_calls`. - - `start_index: Integer` + - `:tool_calls` - The index of the first character of the URL citation in the message. + - `tool_calls: Array[ToolCallDelta]` - - `title: String` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The title of the web resource. + - `class CodeInterpreterToolCallDelta` - - `type: :url_citation` + Details of the Code Interpreter tool call the run step was involved in. - The type of the URL citation. Always `url_citation`. + - `index: Integer` - - `:url_citation` + The index of the tool call in the tool calls array. - - `url: String` + - `type: :code_interpreter` - The URL of the web resource. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class ContainerFileCitation` + - `:code_interpreter` - A citation for a container file used to generate a model response. + - `id: String` - - `container_id: String` + The ID of the tool call. - The ID of the container file. + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `end_index: Integer` + The Code Interpreter tool call definition. - The index of the last character of the container file citation in the message. + - `input: String` - - `file_id: String` + The input to the Code Interpreter tool call. - The ID of the file. + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - - `filename: 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 filename of the container file cited. + - `class CodeInterpreterLogs` - - `start_index: Integer` + Text output from the Code Interpreter tool call as part of a run step. - The index of the first character of the container file citation in the message. + - `index: Integer` - - `type: :container_file_citation` + The index of the output in the outputs array. - The type of the container file citation. Always `container_file_citation`. + - `type: :logs` - - `:container_file_citation` + Always `logs`. - - `class FilePath` + - `:logs` - A path to a file. + - `logs: String` - - `file_id: String` + The text output from the Code Interpreter tool call. - The ID of the file. + - `class CodeInterpreterOutputImage` - `index: Integer` - The index of the file in the list of files. + The index of the output in the outputs array. - - `type: :file_path` + - `type: :image` - The type of the file path. Always `file_path`. + Always `image`. - - `:file_path` + - `:image` - - `text: String` + - `image: Image{ file_id}` - The text output from the model. + - `file_id: String` - - `type: :output_text` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of the output text. Always `output_text`. + - `class FileSearchToolCallDelta` - - `:output_text` + - `file_search: untyped` - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + For now, this is always going to be an empty object. - - `token: String` + - `index: Integer` - - `bytes: Array[Integer]` + The index of the tool call in the tool calls array. - - `logprob: Float` + - `type: :file_search` - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `token: String` + - `:file_search` - - `bytes: Array[Integer]` + - `id: String` - - `logprob: Float` + The ID of the tool call object. - - `class BetaResponseOutputRefusal` + - `class FunctionToolCallDelta` - A refusal from the model. + - `index: Integer` - - `refusal: String` + The index of the tool call in the tool calls array. - The refusal explanation from the model. + - `type: :function` - - `type: :refusal` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the refusal. Always `refusal`. + - `:function` - - `:refusal` + - `id: String` - - `role: :assistant` + The ID of the tool call object. - The role of the output message. Always `assistant`. + - `function: Function{ arguments, name, output}` - - `:assistant` + The definition of the function that was called. - - `status: :in_progress | :completed | :incomplete` + - `arguments: String` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The arguments passed to the function. - - `:in_progress` + - `name: String` - - `:completed` + The name of the function. - - `:incomplete` + - `output: String` - - `type: :message` + 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 type of the output message. Always `message`. +### Run Step Delta Event - - `:message` +- `class RunStepDeltaEvent` - - `agent: Agent{ agent_name}` + Represents a run step delta i.e. any changed fields on a run step during streaming. - The agent that produced this item. + - `id: String` - - `agent_name: String` + The identifier of the run step, which can be referenced in API endpoints. - The canonical name of the agent that produced this item. + - `delta: RunStepDelta` - - `phase: :commentary` + The delta containing the fields that have changed on the run step. - 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. + - `step_details: RunStepDeltaMessageDelta | ToolCallDeltaObject` - - `:commentary` + The details of the run step. - - `class BetaResponseFileSearchToolCall` + - `class RunStepDeltaMessageDelta` - 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. + Details of the message creation by the run step. - - `id: String` + - `type: :message_creation` - The unique ID of the file search tool call. + Always `message_creation`. - - `queries: Array[String]` + - `:message_creation` - The queries used to search for files. + - `message_creation: MessageCreation{ message_id}` - - `status: :in_progress | :searching | :completed | 2 more` + - `message_id: String` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The ID of the message that was created by this run step. - - `:in_progress` + - `class ToolCallDeltaObject` - - `:searching` + Details of the tool call. - - `:completed` + - `type: :tool_calls` - - `:incomplete` + Always `tool_calls`. - - `:failed` + - `:tool_calls` - - `type: :file_search_call` + - `tool_calls: Array[ToolCallDelta]` - The type of the file search tool call. Always `file_search_call`. + 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`. - - `:file_search_call` + - `class CodeInterpreterToolCallDelta` - - `agent: Agent{ agent_name}` + Details of the Code Interpreter tool call the run step was involved in. - The agent that produced this item. + - `index: Integer` - - `agent_name: String` + The index of the tool call in the tool calls array. - The canonical name of the agent that produced this item. + - `type: :code_interpreter` - - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The results of the file search tool call. + - `:code_interpreter` - - `attributes: Hash[Symbol, String | Float | bool]` + - `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 tool call. - - `String = String` + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `Float = Float` + The Code Interpreter tool call definition. - - `UnionMember2 = bool` + - `input: String` - - `file_id: String` + The input to the Code Interpreter tool call. - The unique ID of the file. + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - - `filename: 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 name of the file. + - `class CodeInterpreterLogs` - - `score: Float` + Text output from the Code Interpreter tool call as part of a run step. - The relevance score of the file - a value between 0 and 1. + - `index: Integer` - - `text: String` + The index of the output in the outputs array. - The text that was retrieved from the file. + - `type: :logs` - - `class BetaResponseComputerToolCall` + Always `logs`. - 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. + - `:logs` - - `id: String` + - `logs: String` - The unique ID of the computer call. + The text output from the Code Interpreter tool call. - - `call_id: String` + - `class CodeInterpreterOutputImage` - An identifier used when responding to the tool call with output. + - `index: Integer` - - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + The index of the output in the outputs array. - The pending safety checks for the computer call. + - `type: :image` - - `id: String` + Always `image`. - The ID of the pending safety check. + - `:image` - - `code: String` + - `image: Image{ file_id}` - The type of the pending safety check. + - `file_id: String` - - `message: String` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Details about the pending safety check. + - `class FileSearchToolCallDelta` - - `status: :in_progress | :completed | :incomplete` + - `file_search: untyped` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + For now, this is always going to be an empty object. - - `:in_progress` + - `index: Integer` - - `:completed` + The index of the tool call in the tool calls array. - - `:incomplete` + - `type: :file_search` - - `type: :computer_call` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The type of the computer call. Always `computer_call`. + - `:file_search` - - `:computer_call` + - `id: String` - - `action: BetaComputerAction` + The ID of the tool call object. - A click action. + - `class FunctionToolCallDelta` - - `class Click` + - `index: Integer` - A click action. + The index of the tool call in the tool calls array. - - `button: :left | :right | :wheel | 2 more` + - `type: :function` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `:left` + - `:function` - - `:right` + - `id: String` - - `:wheel` + The ID of the tool call object. - - `:back` + - `function: Function{ arguments, name, output}` - - `:forward` + The definition of the function that was called. - - `type: :click` + - `arguments: String` - Specifies the event type. For a click action, this property is always `click`. + The arguments passed to the function. - - `:click` + - `name: String` - - `x: Integer` + The name of the function. - The x-coordinate where the click occurred. + - `output: String` - - `y_: Integer` + 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 y-coordinate where the click occurred. + - `object: :"thread.run.step.delta"` - - `keys: Array[String]` + The object type, which is always `thread.run.step.delta`. - The keys being held while clicking. + - `:"thread.run.step.delta"` - - `class DoubleClick` +### Run Step Delta Message Delta - A double click action. +- `class RunStepDeltaMessageDelta` - - `keys: Array[String]` + Details of the message creation by the run step. - The keys being held while double-clicking. + - `type: :message_creation` - - `type: :double_click` + Always `message_creation`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `:message_creation` - - `:double_click` + - `message_creation: MessageCreation{ message_id}` - - `x: Integer` + - `message_id: String` - The x-coordinate where the double click occurred. + The ID of the message that was created by this run step. - - `y_: Integer` +### Run Step Include - The y-coordinate where the double click occurred. +- `RunStepInclude = :"step_details.tool_calls[*].file_search.results[*].content"` - - `class Drag` + - `:"step_details.tool_calls[*].file_search.results[*].content"` - A drag action. +### Tool Call - - `path: Array[Path{ x, y_}]` +- `ToolCall = CodeInterpreterToolCall | FileSearchToolCall | FunctionToolCall` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Details of the Code Interpreter tool call the run step was involved in. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `class CodeInterpreterToolCall` - - `x: Integer` + Details of the Code Interpreter tool call the run step was involved in. - The x-coordinate. + - `id: String` - - `y_: Integer` + The ID of the tool call. - The y-coordinate. + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `type: :drag` + The Code Interpreter tool call definition. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `input: String` - - `:drag` + The input to the Code Interpreter tool call. - - `keys: Array[String]` + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - The keys being held while dragging the mouse. + 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. - - `class Keypress` + - `class Logs` - A collection of keypresses the model would like to perform. + Text output from the Code Interpreter tool call as part of a run step. - - `keys: Array[String]` + - `logs: String` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The text output from the Code Interpreter tool call. - - `type: :keypress` + - `type: :logs` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Always `logs`. - - `:keypress` + - `:logs` - - `class Move` + - `class Image` - A mouse move action. + - `image: Image{ file_id}` - - `type: :move` + - `file_id: String` - Specifies the event type. For a move action, this property is always set to `move`. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `:move` + - `type: :image` - - `x: Integer` + Always `image`. - The x-coordinate to move to. + - `:image` - - `y_: Integer` + - `type: :code_interpreter` - The y-coordinate to move to. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `keys: Array[String]` + - `:code_interpreter` - The keys being held while moving the mouse. + - `class FileSearchToolCall` - - `class Screenshot` + - `id: String` - A screenshot action. + The ID of the tool call object. - - `type: :screenshot` + - `file_search: FileSearch{ ranking_options, results}` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + For now, this is always going to be an empty object. - - `:screenshot` + - `ranking_options: RankingOptions{ ranker, score_threshold}` - - `class Scroll` + The ranking options for the file search. - A scroll action. + - `ranker: :auto | :default_2024_08_21` - - `scroll_x: Integer` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The horizontal scroll distance. + - `:auto` - - `scroll_y: Integer` + - `:default_2024_08_21` - The vertical scroll distance. + - `score_threshold: Float` - - `type: :scroll` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `results: Array[Result{ file_id, file_name, score, content}]` - - `:scroll` + The results of the file search. - - `x: Integer` + - `file_id: String` - The x-coordinate where the scroll occurred. + The ID of the file that result was found in. - - `y_: Integer` + - `file_name: String` - The y-coordinate where the scroll occurred. + The name of the file that result was found in. - - `keys: Array[String]` + - `score: Float` - The keys being held while scrolling. + The score of the result. All values must be a floating point number between 0 and 1. - - `class Type` + - `content: Array[Content{ text, type}]` - An action to type in text. + The content of the result that was found. The content is only included if requested via the include query parameter. - `text: String` - The text to type. + The text content of the file. - - `type: :type` + - `type: :text` - Specifies the event type. For a type action, this property is always set to `type`. + The type of the content. - - `:type` + - `:text` - - `class Wait` + - `type: :file_search` - A wait action. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: :wait` + - `:file_search` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `class FunctionToolCall` - - `:wait` + - `id: String` - - `actions: BetaComputerActionList` + The ID of the tool call object. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `function: Function{ arguments, name, output}` - - `class Click` + The definition of the function that was called. - A click action. + - `arguments: String` - - `class DoubleClick` + The arguments passed to the function. - A double click action. + - `name: String` - - `class Drag` + The name of the function. - A drag action. + - `output: String` - - `class Keypress` + 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. - A collection of keypresses the model would like to perform. + - `type: :function` - - `class Move` + The type of tool call. This is always going to be `function` for this type of tool call. - A mouse move action. + - `:function` - - `class Screenshot` +### Tool Call Delta - A screenshot action. +- `ToolCallDelta = CodeInterpreterToolCallDelta | FileSearchToolCallDelta | FunctionToolCallDelta` - - `class Scroll` + Details of the Code Interpreter tool call the run step was involved in. - A scroll action. + - `class CodeInterpreterToolCallDelta` - - `class Type` + Details of the Code Interpreter tool call the run step was involved in. - An action to type in text. + - `index: Integer` - - `class Wait` + The index of the tool call in the tool calls array. - A wait action. + - `type: :code_interpreter` - - `agent: Agent{ 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: String` - The canonical name of the agent that produced this item. + The ID of the tool call. - - `class ComputerCallOutput` + - `code_interpreter: CodeInterpreter{ input, outputs}` - The output of a computer tool call. + The Code Interpreter tool call definition. - - `call_id: String` + - `input: String` - The ID of the computer tool call that produced the output. + The input to the Code Interpreter tool call. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - A computer screenshot image used with the computer use tool. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `type: :computer_screenshot` + - `class CodeInterpreterLogs` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Text output from the Code Interpreter tool call as part of a run step. - - `:computer_screenshot` + - `index: Integer` - - `file_id: String` + The index of the output in the outputs array. - The identifier of an uploaded file that contains the screenshot. + - `type: :logs` - - `image_url: String` + Always `logs`. - The URL of the screenshot image. + - `:logs` - - `type: :computer_call_output` + - `logs: String` - The type of the computer tool call output. Always `computer_call_output`. + The text output from the Code Interpreter tool call. - - `:computer_call_output` + - `class CodeInterpreterOutputImage` - - `id: String` + - `index: Integer` - The ID of the computer tool call output. + The index of the output in the outputs array. - - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + - `type: :image` - The safety checks reported by the API that have been acknowledged by the developer. + Always `image`. - - `id: String` + - `:image` - The ID of the pending safety check. + - `image: Image{ file_id}` - - `code: String` + - `file_id: String` - The type of the pending safety check. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `message: String` + - `class FileSearchToolCallDelta` - Details about the pending safety check. + - `file_search: untyped` - - `agent: Agent{ agent_name}` + For now, this is always going to be an empty object. - The agent that produced this item. + - `index: Integer` - - `agent_name: String` + The index of the tool call in the tool calls array. - The canonical name of the agent that produced this item. + - `type: :file_search` - - `status: :in_progress | :completed | :incomplete` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `:file_search` - - `:in_progress` + - `id: String` - - `:completed` + The ID of the tool call object. - - `:incomplete` + - `class FunctionToolCallDelta` - - `class BetaResponseFunctionWebSearch` + - `index: Integer` - 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 index of the tool call in the tool calls array. - - `id: String` + - `type: :function` - The unique ID of the web search tool call. + The type of tool call. This is always going to be `function` for this type of tool call. - - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + - `:function` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `id: String` - - `class Search` + The ID of the tool call object. - Action type "search" - Performs a web search query. + - `function: Function{ arguments, name, output}` - - `type: :search` + The definition of the function that was called. - The action type. + - `arguments: String` - - `:search` + The arguments passed to the function. - - `queries: Array[String]` + - `name: String` - The search queries. + The name of the function. - - `query: String` + - `output: String` - The search query. + 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. - - `sources: Array[Source{ type, url}]` +### Tool Call Delta Object - The sources used in the search. +- `class ToolCallDeltaObject` - - `type: :url` + Details of the tool call. - The type of source. Always `url`. + - `type: :tool_calls` - - `:url` + Always `tool_calls`. - - `url: String` + - `:tool_calls` - The URL of the source. + - `tool_calls: Array[ToolCallDelta]` - - `class OpenPage` + 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`. - Action type "open_page" - Opens a specific URL from search results. + - `class CodeInterpreterToolCallDelta` - - `type: :open_page` + Details of the Code Interpreter tool call the run step was involved in. - The action type. + - `index: Integer` - - `:open_page` + The index of the tool call in the tool calls array. - - `url: String` + - `type: :code_interpreter` - The URL opened by the model. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class FindInPage` + - `:code_interpreter` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `id: String` - - `pattern: String` + The ID of the tool call. - The pattern or text to search for within the page. + - `code_interpreter: CodeInterpreter{ input, outputs}` - - `type: :find_in_page` + The Code Interpreter tool call definition. - The action type. + - `input: String` - - `:find_in_page` + The input to the Code Interpreter tool call. - - `url: String` + - `outputs: Array[CodeInterpreterLogs | CodeInterpreterOutputImage]` - The URL of the page searched for the pattern. + 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. - - `status: :in_progress | :searching | :completed | :failed` + - `class CodeInterpreterLogs` - The status of the web search tool call. + Text output from the Code Interpreter tool call as part of a run step. - - `:in_progress` + - `index: Integer` - - `:searching` + The index of the output in the outputs array. - - `:completed` + - `type: :logs` - - `:failed` + Always `logs`. - - `type: :web_search_call` + - `:logs` - The type of the web search tool call. Always `web_search_call`. + - `logs: String` - - `:web_search_call` + The text output from the Code Interpreter tool call. - - `agent: Agent{ agent_name}` + - `class CodeInterpreterOutputImage` - The agent that produced this item. + - `index: Integer` - - `agent_name: String` + The index of the output in the outputs array. - The canonical name of the agent that produced this item. + - `type: :image` - - `class BetaResponseFunctionToolCall` + Always `image`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `:image` - - `arguments: String` + - `image: Image{ file_id}` - A JSON string of the arguments to pass to the function. + - `file_id: String` - - `call_id: String` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The unique ID of the function tool call generated by the model. + - `class FileSearchToolCallDelta` - - `name: String` + - `file_search: untyped` - The name of the function to run. + For now, this is always going to be an empty object. - - `type: :function_call` + - `index: Integer` - The type of the function tool call. Always `function_call`. + The index of the tool call in the tool calls array. - - `:function_call` + - `type: :file_search` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `:file_search` - `id: String` - The unique ID of the function tool call. + The ID of the tool call object. - - `agent: Agent{ agent_name}` + - `class FunctionToolCallDelta` - The agent that produced this item. + - `index: Integer` - - `agent_name: String` + The index of the tool call in the tool calls array. - The canonical name of the agent that produced this item. + - `type: :function` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The type of tool call. This is always going to be `function` for this type of tool call. - The execution context that produced this tool call. + - `:function` - - `class Direct` + - `id: String` - - `type: :direct` + The ID of the tool call object. - - `:direct` + - `function: Function{ arguments, name, output}` - - `class Program` + 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. - - `namespace: String` + - `output: String` - The namespace of the function to run. + 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. - - `status: :in_progress | :completed | :incomplete` +### Tool Calls Step Details - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +- `class ToolCallsStepDetails` - - `:in_progress` + Details of the tool call. - - `:completed` + - `tool_calls: Array[ToolCall]` - - `: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`. - - `class FunctionCallOutput` + - `class CodeInterpreterToolCall` - The output of a function tool call. + Details of the Code Interpreter tool call the run step was involved in. - - `call_id: String` + - `id: String` - The unique ID of the function tool call generated by the model. + The ID of the tool call. - - `output: String | BetaResponseFunctionCallOutputItemList` + - `code_interpreter: CodeInterpreter{ input, outputs}` - Text, image, or file output of the function tool call. + The Code Interpreter tool call definition. - - `String = String` + - `input: String` - A JSON string of the output of the function tool call. + The input to the Code Interpreter tool call. - - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + - `outputs: Array[Logs{ logs, type} | Image{ image, type}]` - An array of content outputs (text, image, file) for the function 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. - - `class BetaResponseInputTextContent` + - `class Logs` - A text input to the model. + Text output from the Code Interpreter tool call as part of a run step. - - `text: String` + - `logs: String` - The text input to the model. + The text output from the Code Interpreter tool call. - - `type: :input_text` + - `type: :logs` - The type of the input item. Always `input_text`. + Always `logs`. - - `:input_text` + - `:logs` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class Image` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `image: Image{ file_id}` - - `mode: :explicit` + - `file_id: String` - The breakpoint mode. Always `explicit`. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `:explicit` + - `type: :image` - - `class BetaResponseInputImageContent` + Always `image`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `:image` - - `type: :input_image` + - `type: :code_interpreter` - The type of the input item. Always `input_image`. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `:input_image` + - `:code_interpreter` - - `detail: :low | :high | :auto | :original` + - `class FileSearchToolCall` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `id: String` - - `:low` + The ID of the tool call object. - - `:high` + - `file_search: FileSearch{ ranking_options, results}` - - `:auto` + For now, this is always going to be an empty object. - - `:original` + - `ranking_options: RankingOptions{ ranker, score_threshold}` - - `file_id: String` + The ranking options for the file search. - The ID of the file to be sent to the model. + - `ranker: :auto | :default_2024_08_21` - - `image_url: String` + The ranker to use for the file search. If not specified will use the `auto` ranker. - 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: PromptCacheBreakpoint{ mode}` + - `:default_2024_08_21` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `score_threshold: Float` - - `mode: :explicit` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The breakpoint mode. Always `explicit`. + - `results: Array[Result{ file_id, file_name, score, content}]` - - `:explicit` + The results of the file search. - - `class BetaResponseInputFileContent` + - `file_id: String` - A file input to the model. + The ID of the file that result was found in. - - `type: :input_file` + - `file_name: String` - The type of the input item. Always `input_file`. + The name of the file that result was found in. - - `:input_file` + - `score: Float` - - `detail: :auto | :low | :high` + The score of the result. All values must be a floating point number between 0 and 1. - 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`. + - `content: Array[Content{ text, type}]` - - `:auto` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `:low` + - `text: String` - - `:high` + The text content of the file. - - `file_data: String` + - `type: :text` - The base64-encoded data of the file to be sent to the model. + The type of the content. - - `file_id: String` + - `:text` - The ID of the file to be sent to the model. + - `type: :file_search` - - `file_url: String` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The URL of the file to be sent to the model. + - `:file_search` - - `filename: String` + - `class FunctionToolCall` - The name of the file to be sent to the model. + - `id: String` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + The ID of the tool call 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. + - `function: Function{ arguments, name, output}` - - `mode: :explicit` + The definition of the function that was called. - The breakpoint mode. Always `explicit`. + - `arguments: String` - - `:explicit` + The arguments passed to the function. - - `type: :function_call_output` + - `name: String` - The type of the function tool call output. Always `function_call_output`. + The name of the function. - - `:function_call_output` + - `output: String` - - `id: 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 function tool call output. Populated when this item is returned via API. + - `type: :function` - - `agent: Agent{ 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` + - `type: :tool_calls` - The canonical name of the agent that produced this item. + Always `tool_calls`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:tool_calls` - The execution context that produced this tool call. +# Messages - - `class Direct` +## List messages - - `type: :direct` +`beta.threads.messages.list(thread_id, **kwargs) -> CursorPage` - The caller type. Always `direct`. +**get** `/threads/{thread_id}/messages` - - `:direct` +Returns a list of messages for a given thread. - - `class Program` +### Parameters - - `caller_id: String` +- `thread_id: String` - The call ID of the program item that produced this tool call. +- `after: String` - - `type: :program` + 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 caller type. Always `program`. +- `before: String` - - `:program` + 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. - - `status: :in_progress | :completed | :incomplete` +- `limit: Integer` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `:in_progress` +- `order: :asc | :desc` - - `:completed` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `:incomplete` + - `:asc` - - `class AgentMessage` + - `:desc` - A message routed between agents. +- `run_id: String` - - `author: String` + Filter messages by the run ID that generated them. - The sending agent identity. +### Returns - - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` +- `class Message` - Plaintext, image, or encrypted content sent between agents. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class BetaResponseInputTextContent` + - `id: String` - A text input to the model. + The identifier, which can be referenced in API endpoints. - - `class BetaResponseInputImageContent` + - `assistant_id: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `class EncryptedContent` + - `attachments: Array[Attachment{ file_id, tools}]` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + A list of files attached to the message, and the tools they were added to. - - `encrypted_content: String` + - `file_id: String` - Opaque encrypted content. + The ID of the file to attach to the message. - - `type: :encrypted_content` + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - The type of the input item. Always `encrypted_content`. + The tools to add this file to. - - `:encrypted_content` + - `class CodeInterpreterTool` - - `recipient: String` + - `type: :code_interpreter` - The destination agent identity. + The type of tool being defined: `code_interpreter` - - `type: :agent_message` + - `:code_interpreter` - The item type. Always `agent_message`. + - `class AssistantToolsFileSearchTypeOnly` - - `:agent_message` + - `type: :file_search` - - `id: String` + The type of tool being defined: `file_search` - The unique ID of this agent message item. + - `:file_search` - - `agent: Agent{ agent_name}` + - `completed_at: Integer` - The agent that produced this item. + The Unix timestamp (in seconds) for when the message was completed. - - `agent_name: String` + - `content: Array[MessageContent]` - The canonical name of the agent that produced this item. + The content of the message in array of text and/or images. - - `class MultiAgentCall` + - `class ImageFileContentBlock` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The multi-agent action that was executed. + - `image_file: ImageFile` - - `:spawn_agent` + - `file_id: String` - - `:interrupt_agent` + 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. - - `:list_agents` + - `detail: :auto | :low | :high` - - `:send_message` + 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`. - - `:followup_task` + - `:auto` - - `:wait_agent` + - `:low` - - `arguments: String` + - `:high` - The action arguments as a JSON string. + - `type: :image_file` - - `call_id: String` + Always `image_file`. - The unique ID linking this call to its output. + - `:image_file` - - `type: :multi_agent_call` + - `class ImageURLContentBlock` - The item type. Always `multi_agent_call`. + References an image URL in the content of a message. - - `:multi_agent_call` + - `image_url: ImageURL` - - `id: String` + - `url: String` - The unique ID of this multi-agent call. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `agent: Agent{ agent_name}` + - `detail: :auto | :low | :high` - The agent that produced this item. + 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_name: String` + - `:auto` - The canonical name of the agent that produced this item. + - `:low` - - `class MultiAgentCallOutput` + - `:high` - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` + - `type: :image_url` - The multi-agent action that produced this result. + The type of the content part. - - `:spawn_agent` + - `:image_url` - - `:interrupt_agent` + - `class TextContentBlock` - - `:list_agents` + The text content that is part of a message. - - `:send_message` + - `text: Text` - - `:followup_task` + - `annotations: Array[Annotation]` - - `:wait_agent` + - `class FileCitationAnnotation` - - `call_id: String` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The unique ID of the multi-agent call. + - `end_index: Integer` - - `output: Array[Output{ text, type, annotations}]` + - `file_citation: FileCitation{ file_id}` - Text output returned by the multi-agent action. + - `file_id: String` + + The ID of the specific File the citation is from. + + - `start_index: Integer` - `text: String` - The text content. + The text in the message content that needs to be replaced. - - `type: :output_text` + - `type: :file_citation` - The content type. Always `output_text`. + Always `file_citation`. - - `:output_text` + - `:file_citation` - - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + - `class FilePathAnnotation` - Citations associated with the text content. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + - `end_index: Integer` + + - `file_path: FilePath{ file_id}` - `file_id: String` - The ID of the file. + The ID of the file that was generated. - - `filename: String` + - `start_index: Integer` - The filename of the file cited. + - `text: String` - - `index: Integer` + The text in the message content that needs to be replaced. + + - `type: :file_path` - The index of the file in the list of files. + Always `file_path`. - - `type: :file_citation` + - `:file_path` - The citation type. Always `file_citation`. + - `value: String` - - `:file_citation` + The data that makes up the text. - - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + - `type: :text` - - `end_index: Integer` + Always `text`. - The index of the last character of the citation in the message. + - `:text` - - `start_index: Integer` + - `class RefusalContentBlock` - The index of the first character of the citation in the message. + The refusal content generated by the assistant. - - `title: String` + - `refusal: String` - The title of the cited resource. + - `type: :refusal` - - `type: :url_citation` + Always `refusal`. - The citation type. Always `url_citation`. + - `:refusal` - - `:url_citation` + - `created_at: Integer` - - `url: String` + The Unix timestamp (in seconds) for when the message was created. - The URL of the cited resource. + - `incomplete_at: Integer` - - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `container_id: String` + - `incomplete_details: IncompleteDetails{ reason}` - The ID of the container. + On an incomplete message, details about why the message is incomplete. - - `end_index: Integer` + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - The index of the last character of the citation in the message. + The reason the message is incomplete. - - `file_id: String` + - `:content_filter` - The ID of the container file. + - `:max_tokens` - - `filename: String` + - `:run_cancelled` - The filename of the container file cited. + - `:run_expired` - - `start_index: Integer` + - `:run_failed` - The index of the first character of the citation in the message. + - `metadata: Metadata` - - `type: :container_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. - The citation type. Always `container_file_citation`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `:container_file_citation` + - `object: :"thread.message"` - - `type: :multi_agent_call_output` + The object type, which is always `thread.message`. - The item type. Always `multi_agent_call_output`. + - `:"thread.message"` - - `:multi_agent_call_output` + - `role: :user | :assistant` - - `id: String` + The entity that produced the message. One of `user` or `assistant`. - The unique ID of this multi-agent call output. + - `:user` - - `agent: Agent{ agent_name}` + - `:assistant` - The agent that produced this item. + - `run_id: String` - - `agent_name: 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. - The canonical name of the agent that produced this item. + - `status: :in_progress | :incomplete | :completed` - - `class ToolSearchCall` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `arguments: untyped` + - `:in_progress` - The arguments supplied to the tool search call. + - `:incomplete` - - `type: :tool_search_call` + - `:completed` - The item type. Always `tool_search_call`. + - `thread_id: String` - - `:tool_search_call` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `id: String` +### Example - The unique ID of this tool search call. +```ruby +require "openai" - - `agent: Agent{ agent_name}` +openai = OpenAI::Client.new(api_key: "My API Key") - The agent that produced this item. +page = openai.beta.threads.messages.list("thread_id") - - `agent_name: String` +puts(page) +``` - The canonical name of the agent that produced this item. +#### Response - - `call_id: String` +```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 unique ID of the tool search call generated by the model. +## Create message - - `execution: :server | :client` +`beta.threads.messages.create(thread_id, **kwargs) -> Message` - Whether tool search was executed by the server or by the client. +**post** `/threads/{thread_id}/messages` - - `:server` +Create a message. - - `:client` +### Parameters - - `status: :in_progress | :completed | :incomplete` +- `thread_id: String` - The status of the tool search call. +- `content: String | Array[MessageContentPartParam]` - - `:in_progress` + The text contents of the message. - - `:completed` + - `String = String` - - `:incomplete` + The text contents of the message. - - `class BetaResponseToolSearchOutputItemParam` + - `ArrayOfContentParts = Array[MessageContentPartParam]` - - `tools: Array[BetaTool]` + 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 loaded tool definitions returned by the tool search output. + - `class ImageFileContentBlock` - - `class BetaFunctionTool` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `image_file: ImageFile` - - `name: String` + - `file_id: String` - The name of the function to call. + 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. - - `parameters: Hash[Symbol, untyped]` + - `detail: :auto | :low | :high` - A JSON schema object describing the parameters of the function. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `strict: bool` + - `:auto` - Whether strict parameter validation is enforced for this function tool. + - `:low` - - `type: :function` + - `:high` - The type of the function tool. Always `function`. + - `type: :image_file` - - `:function` + Always `image_file`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:image_file` - The tool invocation context(s). + - `class ImageURLContentBlock` - - `:direct` + References an image URL in the content of a message. - - `:programmatic` + - `image_url: ImageURL` - - `defer_loading: bool` + - `url: String` - Whether this function is deferred and loaded via tool search. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `description: String` + - `detail: :auto | :low | :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`. Default value is `auto` - - `output_schema: Hash[Symbol, untyped]` + - `:auto` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `:low` - - `class BetaFileSearchTool` + - `: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). + - `type: :image_url` - - `type: :file_search` + The type of the content part. - The type of the file search tool. Always `file_search`. + - `:image_url` - - `:file_search` + - `class TextContentBlockParam` - - `vector_store_ids: Array[String]` + The text content that is part of a message. - The IDs of the vector stores to search. + - `text: String` - - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + Text content to be sent to the model - A filter to apply. + - `type: :text` - - `class ComparisonFilter` + Always `text`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `:text` - - `key: String` +- `role: :user | :assistant` - The key to compare against the value. + The role of the entity that is creating the message. Allowed values include: - - `type: :eq | :ne | :gt | 5 more` + - `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. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `:user` - - `eq`: equals - - `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` - - `:eq` +- `attachments: Array[Attachment{ file_id, tools}]` - - `:ne` + A list of files attached to the message, and the tools they should be added to. - - `:gt` + - `file_id: String` - - `:gte` + The ID of the file to attach to the message. - - `:lt` + - `tools: Array[CodeInterpreterTool | FileSearch{ type}]` - - `:lte` + The tools to add this file to. - - `:in` + - `class CodeInterpreterTool` - - `:nin` + - `type: :code_interpreter` - - `value: String | Float | bool | Array[untyped]` + The type of tool being defined: `code_interpreter` - The value to compare against the attribute key; supports string, number, or boolean types. + - `:code_interpreter` - - `String = String` + - `class FileSearch` - - `Float = Float` + - `type: :file_search` - - `UnionMember2 = bool` + The type of tool being defined: `file_search` - - `UnionMember3 = Array[untyped]` + - `:file_search` - - `class CompoundFilter` +- `metadata: Metadata` - Combine multiple filters using `and` or `or`. + Set of 16 key-value pairs that can be attached to an object. 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: Array[ComparisonFilter{ key, type, value} | untyped]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. +### Returns - - `class ComparisonFilter` +- `class Message` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `key: String` + - `id: String` - The key to compare against the value. + The identifier, which can be referenced in API endpoints. - - `type: :eq | :ne | :gt | 5 more` + - `assistant_id: String` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this 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 + - `attachments: Array[Attachment{ file_id, tools}]` - - `:eq` + A list of files attached to the message, and the tools they were added to. - - `:ne` + - `file_id: String` - - `:gt` + The ID of the file to attach to the message. - - `:gte` + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - - `:lt` + The tools to add this file to. - - `:lte` + - `class CodeInterpreterTool` - - `:in` + - `type: :code_interpreter` - - `:nin` + The type of tool being defined: `code_interpreter` - - `value: String | Float | bool | Array[untyped]` + - `:code_interpreter` - The value to compare against the attribute key; supports string, number, or boolean types. + - `class AssistantToolsFileSearchTypeOnly` - - `String = String` + - `type: :file_search` - - `Float = Float` + The type of tool being defined: `file_search` - - `UnionMember2 = bool` + - `:file_search` - - `UnionMember3 = Array[untyped]` + - `completed_at: Integer` - - `UnionMember1 = untyped` + The Unix timestamp (in seconds) for when the message was completed. - - `type: :and | :or` + - `content: Array[MessageContent]` - Type of operation: `and` or `or`. + The content of the message in array of text and/or images. - - `:and` + - `class ImageFileContentBlock` - - `:or` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `max_num_results: Integer` + - `image_file: ImageFile` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `file_id: String` - - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + 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. - Ranking options for search. + - `detail: :auto | :low | :high` - - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + 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`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `:auto` - - `embedding_weight: Float` + - `:low` - The weight of the embedding in the reciprocal ranking fusion. + - `:high` - - `text_weight: Float` + - `type: :image_file` - The weight of the text in the reciprocal ranking fusion. + Always `image_file`. - - `ranker: :auto | :"default-2024-11-15"` + - `:image_file` - The ranker to use for the file search. + - `class ImageURLContentBlock` - - `:auto` + References an image URL in the content of a message. - - `:"default-2024-11-15"` + - `image_url: ImageURL` - - `score_threshold: Float` + - `url: 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 external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `class BetaComputerTool` + - `detail: :auto | :low | :high` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: :computer` + - `:auto` - The type of the computer tool. Always `computer`. + - `:low` - - `:computer` + - `:high` - - `class BetaComputerUsePreviewTool` + - `type: :image_url` - 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 content part. - - `display_height: Integer` + - `:image_url` - The height of the computer display. + - `class TextContentBlock` - - `display_width: Integer` + The text content that is part of a message. - The width of the computer display. + - `text: Text` - - `environment: :windows | :mac | :linux | 2 more` + - `annotations: Array[Annotation]` - The type of computer environment to control. + - `class FileCitationAnnotation` - - `:windows` + 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. - - `:mac` + - `end_index: Integer` - - `:linux` + - `file_citation: FileCitation{ file_id}` - - `:ubuntu` + - `file_id: String` - - `:browser` + The ID of the specific File the citation is from. - - `type: :computer_use_preview` + - `start_index: Integer` - The type of the computer use tool. Always `computer_use_preview`. + - `text: String` - - `:computer_use_preview` + The text in the message content that needs to be replaced. - - `class BetaWebSearchTool` + - `type: :file_citation` - 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). + Always `file_citation`. - - `type: :web_search | :web_search_2025_08_26` + - `:file_citation` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `class FilePathAnnotation` - - `:web_search` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `:web_search_2025_08_26` + - `end_index: Integer` - - `filters: Filters{ allowed_domains}` + - `file_path: FilePath{ file_id}` - Filters for the search. + - `file_id: String` - - `allowed_domains: Array[String]` + The ID of the file that was generated. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `start_index: Integer` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `text: String` - - `search_context_size: :low | :medium | :high` + The text in the message content that needs to be replaced. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `type: :file_path` - - `:low` + Always `file_path`. - - `:medium` + - `:file_path` - - `:high` + - `value: String` - - `user_location: UserLocation{ city, country, region, 2 more}` + The data that makes up the text. - The approximate location of the user. + - `type: :text` - - `city: String` + Always `text`. - Free text input for the city of the user, e.g. `San Francisco`. + - `:text` - - `country: String` + - `class RefusalContentBlock` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The refusal content generated by the assistant. - - `region: String` + - `refusal: String` - Free text input for the region of the user, e.g. `California`. + - `type: :refusal` - - `timezone: String` + Always `refusal`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `:refusal` - - `type: :approximate` + - `created_at: Integer` - The type of location approximation. Always `approximate`. + The Unix timestamp (in seconds) for when the message was created. - - `:approximate` + - `incomplete_at: Integer` - - `class Mcp` + The Unix timestamp (in seconds) for when the message was marked as 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). + - `incomplete_details: IncompleteDetails{ reason}` - - `server_label: String` + On an incomplete message, details about why the message is incomplete. - A label for this MCP server, used to identify it in tool calls. + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - - `type: :mcp` + The reason the message is incomplete. - The type of the MCP tool. Always `mcp`. + - `:content_filter` - - `:mcp` + - `:max_tokens` - - `allowed_callers: Array[:direct | :programmatic]` + - `:run_cancelled` - The tool invocation context(s). + - `:run_expired` - - `:direct` + - `:run_failed` - - `:programmatic` + - `metadata: Metadata` - - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - List of allowed tool names or a filter object. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `McpAllowedTools = Array[String]` + - `object: :"thread.message"` - A string array of allowed tool names + The object type, which is always `thread.message`. - - `class McpToolFilter` + - `:"thread.message"` - A filter object to specify which tools are allowed. + - `role: :user | :assistant` - - `read_only: bool` + The entity that produced the message. One of `user` or `assistant`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `:user` - - `tool_names: Array[String]` + - `:assistant` - List of allowed tool names. + - `run_id: String` - - `authorization: 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. - 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. + - `status: :in_progress | :incomplete | :completed` - - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + The status of the message, which can be either `in_progress`, `incomplete`, or `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). + - `:in_progress` - Currently supported `connector_id` values are: + - `:incomplete` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `:completed` - - `:connector_dropbox` + - `thread_id: String` - - `:connector_gmail` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `:connector_googlecalendar` +### Example - - `:connector_googledrive` +```ruby +require "openai" - - `:connector_microsoftteams` +openai = OpenAI::Client.new(api_key: "My API Key") - - `:connector_outlookcalendar` +message = openai.beta.threads.messages.create("thread_id", content: "string", role: :user) - - `:connector_outlookemail` +puts(message) +``` - - `:connector_sharepoint` +#### Response - - `defer_loading: bool` +```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" +} +``` - Whether this MCP tool is deferred and discovered via tool search. +## Modify message - - `headers: Hash[Symbol, String]` +`beta.threads.messages.update(message_id, **kwargs) -> Message` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. +**post** `/threads/{thread_id}/messages/{message_id}` - - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` +Modifies a message. - Specify which of the MCP server's tools require approval. +### Parameters - - `class McpToolApprovalFilter` +- `thread_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. +- `message_id: String` - - `always: Always{ read_only, tool_names}` +- `metadata: 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: bool` + 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. +### Returns - - `tool_names: Array[String]` +- `class Message` - List of allowed tool names. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `never: Never{ read_only, tool_names}` + - `id: String` - A filter object to specify which tools are allowed. + The identifier, which can be referenced in API endpoints. - - `read_only: bool` + - `assistant_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. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `tool_names: Array[String]` + - `attachments: Array[Attachment{ file_id, tools}]` - List of allowed tool names. + A list of files attached to the message, and the tools they were added to. - - `McpToolApprovalSetting = :always | :never` + - `file_id: String` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The ID of the file to attach to the message. - - `:always` + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - - `:never` + The tools to add this file to. - - `server_description: String` + - `class CodeInterpreterTool` - Optional description of the MCP server, used to provide more context. + - `type: :code_interpreter` - - `server_url: String` + The type of tool being defined: `code_interpreter` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `:code_interpreter` - - `tunnel_id: String` + - `class AssistantToolsFileSearchTypeOnly` - 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: :file_search` - - `class CodeInterpreter` + The type of tool being defined: `file_search` - A tool that runs Python code to help generate a response to a prompt. + - `:file_search` - - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + - `completed_at: Integer` - 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 Unix timestamp (in seconds) for when the message was completed. - - `String = String` + - `content: Array[MessageContent]` - The container ID. + The content of the message in array of text and/or images. - - `class CodeInterpreterToolAuto` + - `class ImageFileContentBlock` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `type: :auto` + - `image_file: ImageFile` - Always `auto`. + - `file_id: String` - - `:auto` + 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. - - `file_ids: Array[String]` + - `detail: :auto | :low | :high` - An optional list of uploaded files to make available to your code. + 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`. - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:auto` - The memory limit for the code interpreter container. + - `:low` - - `:"1g"` + - `:high` - - `:"4g"` + - `type: :image_file` - - `:"16g"` + Always `image_file`. - - `:"64g"` + - `:image_file` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + - `class ImageURLContentBlock` - Network access policy for the container. + References an image URL in the content of a message. - - `class BetaContainerNetworkPolicyDisabled` + - `image_url: ImageURL` - - `type: :disabled` + - `url: String` - Disable outbound network access. Always `disabled`. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `:disabled` + - `detail: :auto | :low | :high` - - `class BetaContainerNetworkPolicyAllowlist` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `allowed_domains: Array[String]` + - `:auto` - A list of allowed domains when type is `allowlist`. + - `:low` - - `type: :allowlist` + - `:high` - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: :image_url` - - `:allowlist` + The type of the content part. - - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` + - `:image_url` - Optional domain-scoped secrets for allowlisted domains. + - `class TextContentBlock` - - `domain: String` + The text content that is part of a message. - The domain associated with the secret. + - `text: Text` - - `name: String` + - `annotations: Array[Annotation]` - The name of the secret to inject for the domain. + - `class FileCitationAnnotation` - - `value: String` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The secret value to inject for the domain. + - `end_index: Integer` - - `type: :code_interpreter` + - `file_citation: FileCitation{ file_id}` - The type of the code interpreter tool. Always `code_interpreter`. + - `file_id: String` - - `:code_interpreter` + The ID of the specific File the citation is from. - - `allowed_callers: Array[:direct | :programmatic]` + - `start_index: Integer` - The tool invocation context(s). + - `text: String` - - `:direct` + The text in the message content that needs to be replaced. - - `:programmatic` + - `type: :file_citation` - - `class ProgrammaticToolCalling` + Always `file_citation`. - - `type: :programmatic_tool_calling` + - `:file_citation` - The type of the tool. Always `programmatic_tool_calling`. + - `class FilePathAnnotation` - - `:programmatic_tool_calling` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `class ImageGeneration` + - `end_index: Integer` - A tool that generates images using the GPT image models. + - `file_path: FilePath{ file_id}` - - `type: :image_generation` + - `file_id: String` - The type of the image generation tool. Always `image_generation`. + The ID of the file that was generated. - - `:image_generation` + - `start_index: Integer` - - `action: :generate | :edit | :auto` + - `text: String` - Whether to generate a new image or edit an existing image. Default: `auto`. + The text in the message content that needs to be replaced. - - `:generate` + - `type: :file_path` - - `:edit` + Always `file_path`. - - `:auto` + - `:file_path` - - `background: :transparent | :opaque | :auto` + - `value: 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 data that makes up the text. - `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: :text` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Always `text`. - - `:transparent` + - `:text` - - `:opaque` + - `class RefusalContentBlock` - - `:auto` + The refusal content generated by the assistant. - - `input_fidelity: :high | :low` + - `refusal: 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`. + - `type: :refusal` - - `:high` + Always `refusal`. - - `:low` + - `:refusal` - - `input_image_mask: InputImageMask{ file_id, image_url}` + - `created_at: Integer` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The Unix timestamp (in seconds) for when the message was created. - - `file_id: String` + - `incomplete_at: Integer` - File ID for the mask image. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `image_url: String` + - `incomplete_details: IncompleteDetails{ reason}` - Base64-encoded mask image. + On an incomplete message, details about why the message is incomplete. - - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - The image generation model to use. Default: `gpt-image-1`. + The reason the message is incomplete. - - `String = String` + - `:content_filter` - - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + - `:max_tokens` - The image generation model to use. Default: `gpt-image-1`. + - `:run_cancelled` - - `:"gpt-image-1"` + - `:run_expired` - - `:"gpt-image-1-mini"` + - `:run_failed` - - `:"gpt-image-2"` + - `metadata: Metadata` - - `:"gpt-image-2-2026-04-21"` + Set of 16 key-value pairs that can be attached to an object. 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-image-1.5"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `:"chatgpt-image-latest"` + - `object: :"thread.message"` - - `moderation: :auto | :low` + The object type, which is always `thread.message`. - Moderation level for the generated image. Default: `auto`. + - `:"thread.message"` - - `:auto` + - `role: :user | :assistant` - - `:low` + The entity that produced the message. One of `user` or `assistant`. - - `output_compression: Integer` + - `:user` - Compression level for the output image. Default: 100. + - `:assistant` - - `output_format: :png | :webp | :jpeg` + - `run_id: String` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + 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. - - `:png` + - `status: :in_progress | :incomplete | :completed` - - `:webp` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `:jpeg` + - `:in_progress` - - `partial_images: Integer` + - `:incomplete` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `:completed` - - `quality: :low | :medium | :high | :auto` + - `thread_id: String` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `:low` +### Example - - `:medium` +```ruby +require "openai" - - `:high` +openai = OpenAI::Client.new(api_key: "My API Key") - - `:auto` +message = openai.beta.threads.messages.update("message_id", thread_id: "thread_id") - - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` +puts(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`. +#### Response - - `String = String` +```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" +} +``` - - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` +## Retrieve 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`. +`beta.threads.messages.retrieve(message_id, **kwargs) -> Message` - - `:"1024x1024"` +**get** `/threads/{thread_id}/messages/{message_id}` - - `:"1024x1536"` +Retrieve a message. - - `:"1536x1024"` +### Parameters - - `:auto` +- `thread_id: String` - - `class LocalShell` +- `message_id: String` - A tool that allows the model to execute shell commands in a local environment. +### Returns - - `type: :local_shell` +- `class Message` - The type of the local shell tool. Always `local_shell`. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `:local_shell` + - `id: String` - - `class BetaFunctionShellTool` + The identifier, which can be referenced in API endpoints. - A tool that allows the model to execute shell commands. + - `assistant_id: String` - - `type: :shell` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - The type of the shell tool. Always `shell`. + - `attachments: Array[Attachment{ file_id, tools}]` - - `:shell` + A list of files attached to the message, and the tools they were added to. - - `allowed_callers: Array[:direct | :programmatic]` + - `file_id: String` - The tool invocation context(s). + The ID of the file to attach to the message. - - `:direct` + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - - `:programmatic` + The tools to add this file to. - - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + - `class CodeInterpreterTool` - - `class BetaContainerAuto` + - `type: :code_interpreter` - - `type: :container_auto` + The type of tool being defined: `code_interpreter` - Automatically creates a container for this request + - `:code_interpreter` - - `:container_auto` + - `class AssistantToolsFileSearchTypeOnly` - - `file_ids: Array[String]` + - `type: :file_search` - An optional list of uploaded files to make available to your code. + The type of tool being defined: `file_search` - - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + - `:file_search` - The memory limit for the container. + - `completed_at: Integer` - - `:"1g"` + The Unix timestamp (in seconds) for when the message was completed. - - `:"4g"` + - `content: Array[MessageContent]` - - `:"16g"` + The content of the message in array of text and/or images. - - `:"64g"` + - `class ImageFileContentBlock` - - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Network access policy for the container. + - `image_file: ImageFile` - - `class BetaContainerNetworkPolicyDisabled` + - `file_id: String` - - `class BetaContainerNetworkPolicyAllowlist` + 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. - - `skills: Array[BetaSkillReference | BetaInlineSkill]` + - `detail: :auto | :low | :high` - An optional list of skills referenced by id or inline data. + 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`. - - `class BetaSkillReference` + - `:auto` - - `skill_id: String` + - `:low` - The ID of the referenced skill. + - `:high` - - `type: :skill_reference` + - `type: :image_file` - References a skill created with the /v1/skills endpoint. + Always `image_file`. - - `:skill_reference` + - `:image_file` - - `version: String` + - `class ImageURLContentBlock` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + References an image URL in the content of a message. - - `class BetaInlineSkill` + - `image_url: ImageURL` - - `description: String` + - `url: String` - The description of the skill. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `name: String` + - `detail: :auto | :low | :high` - The name of the skill. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `source: BetaInlineSkillSource` + - `:auto` - Inline skill payload + - `:low` - - `data: String` + - `:high` - Base64-encoded skill zip bundle. + - `type: :image_url` - - `media_type: :"application/zip"` + The type of the content part. - The media type of the inline skill payload. Must be `application/zip`. + - `:image_url` - - `:"application/zip"` + - `class TextContentBlock` - - `type: :base64` + The text content that is part of a message. - The type of the inline skill source. Must be `base64`. + - `text: Text` - - `:base64` + - `annotations: Array[Annotation]` - - `type: :inline` + - `class FileCitationAnnotation` - Defines an inline skill for this request. + 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. - - `:inline` + - `end_index: Integer` - - `class BetaLocalEnvironment` + - `file_citation: FileCitation{ file_id}` - - `type: :local` + - `file_id: String` - Use a local computer environment. + The ID of the specific File the citation is from. - - `:local` + - `start_index: Integer` - - `skills: Array[BetaLocalSkill]` + - `text: String` - An optional list of skills. + The text in the message content that needs to be replaced. - - `description: String` + - `type: :file_citation` - The description of the skill. + Always `file_citation`. - - `name: String` + - `:file_citation` - The name of the skill. + - `class FilePathAnnotation` - - `path: String` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The path to the directory containing the skill. + - `end_index: Integer` - - `class BetaContainerReference` + - `file_path: FilePath{ file_id}` - - `container_id: String` + - `file_id: String` - The ID of the referenced container. + The ID of the file that was generated. - - `type: :container_reference` + - `start_index: Integer` - References a container created with the /v1/containers endpoint + - `text: String` - - `:container_reference` + The text in the message content that needs to be replaced. - - `class BetaCustomTool` + - `type: :file_path` - 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) + Always `file_path`. - - `name: String` + - `:file_path` - The name of the custom tool, used to identify it in tool calls. + - `value: String` - - `type: :custom` + The data that makes up the text. - The type of the custom tool. Always `custom`. + - `type: :text` - - `:custom` + Always `text`. - - `allowed_callers: Array[:direct | :programmatic]` + - `:text` - The tool invocation context(s). + - `class RefusalContentBlock` - - `:direct` + The refusal content generated by the assistant. - - `:programmatic` + - `refusal: String` - - `defer_loading: bool` + - `type: :refusal` - Whether this tool should be deferred and discovered via tool search. + Always `refusal`. - - `description: String` + - `:refusal` - Optional description of the custom tool, used to provide more context. + - `created_at: Integer` - - `format_: Text{ type} | Grammar{ definition, syntax, type}` + The Unix timestamp (in seconds) for when the message was created. - The input format for the custom tool. Default is unconstrained text. + - `incomplete_at: Integer` - - `class Text` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - Unconstrained free-form text. + - `incomplete_details: IncompleteDetails{ reason}` - - `type: :text` + On an incomplete message, details about why the message is incomplete. - Unconstrained text format. Always `text`. + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - - `:text` + The reason the message is incomplete. - - `class Grammar` + - `:content_filter` - A grammar defined by the user. + - `:max_tokens` - - `definition: String` + - `:run_cancelled` - The grammar definition. + - `:run_expired` - - `syntax: :lark | :regex` + - `:run_failed` - The syntax of the grammar definition. One of `lark` or `regex`. + - `metadata: Metadata` - - `:lark` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `:regex` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: :grammar` + - `object: :"thread.message"` - Grammar format. Always `grammar`. + The object type, which is always `thread.message`. - - `:grammar` + - `:"thread.message"` - - `class BetaNamespaceTool` + - `role: :user | :assistant` - Groups function/custom tools under a shared namespace. + The entity that produced the message. One of `user` or `assistant`. - - `description: String` + - `:user` - A description of the namespace shown to the model. + - `:assistant` - - `name: String` + - `run_id: String` - The namespace name used in tool calls (for example, `crm`). + 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. - - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + - `status: :in_progress | :incomplete | :completed` - The function/custom tools available inside this namespace. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `class Function` + - `:in_progress` - - `name: String` + - `:incomplete` - - `type: :function` + - `:completed` - - `:function` + - `thread_id: String` - - `allowed_callers: Array[:direct | :programmatic]` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The tool invocation context(s). +### Example - - `:direct` +```ruby +require "openai" - - `:programmatic` +openai = OpenAI::Client.new(api_key: "My API Key") - - `defer_loading: bool` +message = openai.beta.threads.messages.retrieve("message_id", thread_id: "thread_id") - Whether this function should be deferred and discovered via tool search. +puts(message) +``` - - `description: String` +#### Response - - `output_schema: Hash[Symbol, untyped]` +```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" +} +``` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +## Delete message - - `parameters: untyped` +`beta.threads.messages.delete(message_id, **kwargs) -> MessageDeleted` - - `strict: bool` +**delete** `/threads/{thread_id}/messages/{message_id}` - 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. +Deletes a message. - - `class BetaCustomTool` +### 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) +- `thread_id: String` - - `type: :namespace` +- `message_id: String` - The type of the tool. Always `namespace`. +### Returns - - `:namespace` +- `class MessageDeleted` - - `class BetaToolSearchTool` + - `id: String` - Hosted or BYOT tool search configuration for deferred tools. + - `deleted: bool` - - `type: :tool_search` + - `object: :"thread.message.deleted"` - The type of the tool. Always `tool_search`. + - `:"thread.message.deleted"` - - `:tool_search` +### Example - - `description: String` +```ruby +require "openai" - Description shown to the model for a client-executed tool search tool. +openai = OpenAI::Client.new(api_key: "My API Key") - - `execution: :server | :client` +message_deleted = openai.beta.threads.messages.delete("message_id", thread_id: "thread_id") - Whether tool search is executed by the server or by the client. +puts(message_deleted) +``` - - `:server` +#### Response - - `:client` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` - - `parameters: untyped` +## Domain Types - Parameter schema for a client-executed tool search tool. +### Annotation - - `class BetaWebSearchPreviewTool` +- `Annotation = FileCitationAnnotation | FilePathAnnotation` - 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 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: :web_search_preview | :web_search_preview_2025_03_11` + - `class FileCitationAnnotation` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + 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_preview` + - `end_index: Integer` - - `:web_search_preview_2025_03_11` + - `file_citation: FileCitation{ file_id}` - - `search_content_types: Array[:text | :image]` + - `file_id: String` - - `:text` + The ID of the specific File the citation is from. - - `:image` + - `start_index: Integer` - - `search_context_size: :low | :medium | :high` + - `text: String` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The text in the message content that needs to be replaced. - - `:low` + - `type: :file_citation` - - `:medium` + Always `file_citation`. - - `:high` + - `:file_citation` - - `user_location: UserLocation{ type, city, country, 2 more}` + - `class FilePathAnnotation` - The user's location. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `type: :approximate` + - `end_index: Integer` - The type of location approximation. Always `approximate`. + - `file_path: FilePath{ file_id}` - - `:approximate` + - `file_id: String` - - `city: String` + The ID of the file that was generated. - Free text input for the city of the user, e.g. `San Francisco`. + - `start_index: Integer` - - `country: String` + - `text: String` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The text in the message content that needs to be replaced. - - `region: String` + - `type: :file_path` - Free text input for the region of the user, e.g. `California`. + Always `file_path`. - - `timezone: String` + - `:file_path` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +### Annotation Delta - - `class BetaApplyPatchTool` +- `AnnotationDelta = FileCitationDeltaAnnotation | FilePathDeltaAnnotation` - Allows the assistant to create, delete, or update files using unified diffs. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `type: :apply_patch` + - `class FileCitationDeltaAnnotation` - The type of the tool. Always `apply_patch`. + 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. - - `:apply_patch` + - `index: Integer` - - `allowed_callers: Array[:direct | :programmatic]` + The index of the annotation in the text content part. - The tool invocation context(s). + - `type: :file_citation` - - `:direct` + Always `file_citation`. - - `:programmatic` + - `:file_citation` - - `type: :tool_search_output` + - `end_index: Integer` - The item type. Always `tool_search_output`. + - `file_citation: FileCitation{ file_id, quote}` - - `:tool_search_output` + - `file_id: String` - - `id: String` + The ID of the specific File the citation is from. - The unique ID of this tool search output. + - `quote: String` - - `agent: Agent{ agent_name}` + The specific quote in the file. - The agent that produced this item. + - `start_index: Integer` - - `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. - - `call_id: String` + - `class FilePathDeltaAnnotation` - The unique ID of the tool search call generated by the model. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `execution: :server | :client` + - `index: Integer` - Whether tool search was executed by the server or by the client. + The index of the annotation in the text content part. - - `:server` + - `type: :file_path` - - `:client` + Always `file_path`. - - `status: :in_progress | :completed | :incomplete` + - `:file_path` - The status of the tool search output. + - `end_index: Integer` - - `:in_progress` + - `file_path: FilePath{ file_id}` - - `:completed` + - `file_id: String` - - `:incomplete` + The ID of the file that was generated. - - `class AdditionalTools` + - `start_index: Integer` - - `role: :developer` + - `text: String` - The role that provided the additional tools. Only `developer` is supported. + The text in the message content that needs to be replaced. - - `:developer` +### File Citation Annotation - - `tools: Array[BetaTool]` +- `class FileCitationAnnotation` - A list of additional tools made available at this 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. - - `class BetaFunctionTool` + - `end_index: Integer` - 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_citation: FileCitation{ file_id}` - - `class BetaFileSearchTool` + - `file_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 specific File the citation is from. - - `class BetaComputerTool` + - `start_index: Integer` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `text: String` - - `class BetaComputerUsePreviewTool` + The text in the message content that needs to be replaced. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: :file_citation` - - `class BetaWebSearchTool` + Always `file_citation`. - 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). + - `:file_citation` - - `class Mcp` +### File Citation Delta Annotation - 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). +- `class FileCitationDeltaAnnotation` - - `class CodeInterpreter` + 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 that runs Python code to help generate a response to a prompt. + - `index: Integer` - - `class ProgrammaticToolCalling` + The index of the annotation in the text content part. - - `class ImageGeneration` + - `type: :file_citation` - A tool that generates images using the GPT image models. + Always `file_citation`. - - `class LocalShell` + - `:file_citation` - A tool that allows the model to execute shell commands in a local environment. + - `end_index: Integer` - - `class BetaFunctionShellTool` + - `file_citation: FileCitation{ file_id, quote}` - A tool that allows the model to execute shell commands. + - `file_id: String` - - `class BetaCustomTool` + The ID of the specific File the citation is from. - 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) + - `quote: String` - - `class BetaNamespaceTool` + The specific quote in the file. - Groups function/custom tools under a shared namespace. + - `start_index: Integer` - - `class BetaToolSearchTool` + - `text: String` - Hosted or BYOT tool search configuration for deferred tools. + The text in the message content that needs to be replaced. - - `class BetaWebSearchPreviewTool` +### File Path Annotation - 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). +- `class FilePathAnnotation` - - `class BetaApplyPatchTool` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Allows the assistant to create, delete, or update files using unified diffs. + - `end_index: Integer` - - `type: :additional_tools` + - `file_path: FilePath{ file_id}` - The item type. Always `additional_tools`. + - `file_id: String` - - `:additional_tools` + The ID of the file that was generated. - - `id: String` + - `start_index: Integer` - The unique ID of this additional tools item. + - `text: String` - - `agent: Agent{ 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` - - `class BetaResponseReasoningItem` +### File Path Delta Annotation - 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). +- `class FilePathDeltaAnnotation` - - `id: String` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The unique identifier of the reasoning content. + - `index: Integer` - - `summary: Array[Summary{ text, type}]` + The index of the annotation in the text content part. - Reasoning summary content. + - `type: :file_path` - - `text: String` + Always `file_path`. - A summary of the reasoning output from the model so far. + - `:file_path` - - `type: :summary_text` + - `end_index: Integer` - The type of the object. Always `summary_text`. + - `file_path: FilePath{ file_id}` - - `:summary_text` + - `file_id: String` - - `type: :reasoning` + The ID of the file that was generated. - The type of the object. Always `reasoning`. + - `start_index: Integer` - - `:reasoning` + - `text: String` - - `agent: Agent{ agent_name}` + The text in the message content that needs to be replaced. - The agent that produced this item. +### Image File - - `agent_name: String` +- `class ImageFile` - The canonical name of the agent that produced this item. + - `file_id: String` - - `content: Array[Content{ text, 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. - Reasoning text content. + - `detail: :auto | :low | :high` - - `text: 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 reasoning text from the model. + - `:auto` - - `type: :reasoning_text` + - `:low` - The type of the reasoning text. Always `reasoning_text`. + - `:high` - - `:reasoning_text` +### Image File Content Block - - `encrypted_content: String` +- `class ImageFileContentBlock` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `status: :in_progress | :completed | :incomplete` + - `image_file: ImageFile` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_id: String` - - `:in_progress` + The [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. - - `:completed` + - `detail: :auto | :low | :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`. - - `class BetaResponseCompactionItemParam` + - `:auto` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `:low` - - `encrypted_content: String` + - `:high` - The encrypted content of the compaction summary. + - `type: :image_file` - - `type: :compaction` + Always `image_file`. - The type of the item. Always `compaction`. + - `:image_file` - - `:compaction` +### Image File Delta - - `id: String` +- `class ImageFileDelta` - The ID of the compaction item. + - `detail: :auto | :low | :high` - - `agent: Agent{ 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` - - `class ImageGenerationCall` + - `file_id: String` - An image generation request made by the model. + 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. - - `id: String` +### Image File Delta Block - The unique ID of the image generation call. +- `class ImageFileDeltaBlock` - - `result: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The generated image encoded in base64. + - `index: Integer` - - `status: :in_progress | :completed | :generating | :failed` + The index of the content part in the message. - The status of the image generation call. + - `type: :image_file` - - `:in_progress` + Always `image_file`. - - `:completed` + - `:image_file` - - `:generating` + - `image_file: ImageFileDelta` - - `:failed` + - `detail: :auto | :low | :high` - - `type: :image_generation_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`. - The type of the image generation call. Always `image_generation_call`. + - `:auto` - - `:image_generation_call` + - `:low` - - `agent: Agent{ agent_name}` + - `:high` - The agent that produced this item. + - `file_id: String` - - `agent_name: 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 canonical name of the agent that produced this item. +### Image URL - - `class BetaResponseCodeInterpreterToolCall` +- `class ImageURL` - A tool call to run code. + - `url: String` - - `id: String` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The unique ID of the code interpreter tool call. + - `detail: :auto | :low | :high` - - `code: 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 code to run, or null if not available. + - `:auto` - - `container_id: String` + - `:low` - The ID of the container used to run the code. + - `:high` - - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` +### Image URL Content Block - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. +- `class ImageURLContentBlock` - - `class Logs` + References an image URL in the content of a message. - The logs output from the code interpreter. + - `image_url: ImageURL` - - `logs: String` + - `url: String` - The logs output from the code interpreter. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `type: :logs` + - `detail: :auto | :low | :high` - The type of the output. Always `logs`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `:logs` + - `:auto` - - `class Image` + - `:low` - The image output from the code interpreter. + - `:high` - - `type: :image` + - `type: :image_url` - The type of the output. Always `image`. + The type of the content part. - - `:image` + - `:image_url` - - `url: String` +### Image URL Delta - The URL of the image output from the code interpreter. +- `class ImageURLDelta` - - `status: :in_progress | :completed | :incomplete | 2 more` + - `detail: :auto | :low | :high` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `:in_progress` + - `:auto` - - `:completed` + - `:low` - - `:incomplete` + - `:high` - - `:interpreting` + - `url: String` - - `:failed` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `type: :code_interpreter_call` +### Image URL Delta Block - The type of the code interpreter tool call. Always `code_interpreter_call`. +- `class ImageURLDeltaBlock` - - `:code_interpreter_call` + References an image URL in the content of a message. - - `agent: Agent{ agent_name}` + - `index: Integer` - The agent that produced this item. + The index of the content part in the message. - - `agent_name: String` + - `type: :image_url` - The canonical name of the agent that produced this item. + Always `image_url`. - - `class LocalShellCall` + - `:image_url` - A tool call to run a command on the local shell. + - `image_url: ImageURLDelta` - - `id: String` + - `detail: :auto | :low | :high` - The unique ID of the local shell call. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `action: Action{ command, env, type, 3 more}` + - `:auto` - Execute a shell command on the server. + - `:low` - - `command: Array[String]` + - `:high` - The command to run. + - `url: String` - - `env: Hash[Symbol, String]` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Environment variables to set for the command. +### Message - - `type: :exec` +- `class Message` - The type of the local shell action. Always `exec`. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `:exec` + - `id: String` - - `timeout_ms: Integer` + The identifier, which can be referenced in API endpoints. - Optional timeout in milliseconds for the command. + - `assistant_id: String` - - `user: String` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - Optional user to run the command as. + - `attachments: Array[Attachment{ file_id, tools}]` - - `working_directory: String` + A list of files attached to the message, and the tools they were added to. - Optional working directory to run the command in. + - `file_id: String` - - `call_id: String` + The ID of the file to attach to the message. - The unique ID of the local shell tool call generated by the model. + - `tools: Array[CodeInterpreterTool | AssistantToolsFileSearchTypeOnly{ type}]` - - `status: :in_progress | :completed | :incomplete` + The tools to add this file to. - The status of the local shell call. + - `class CodeInterpreterTool` - - `:in_progress` + - `type: :code_interpreter` - - `:completed` + The type of tool being defined: `code_interpreter` - - `:incomplete` + - `:code_interpreter` - - `type: :local_shell_call` + - `class AssistantToolsFileSearchTypeOnly` - The type of the local shell call. Always `local_shell_call`. + - `type: :file_search` - - `:local_shell_call` + The type of tool being defined: `file_search` - - `agent: Agent{ agent_name}` + - `:file_search` - The agent that produced this item. + - `completed_at: Integer` - - `agent_name: String` + The Unix timestamp (in seconds) for when the message was completed. - The canonical name of the agent that produced this item. + - `content: Array[MessageContent]` - - `class LocalShellCallOutput` + The content of the message in array of text and/or images. - The output of a local shell tool call. + - `class ImageFileContentBlock` - - `id: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The unique ID of the local shell tool call generated by the model. + - `image_file: ImageFile` - - `output: String` + - `file_id: String` - A JSON string of the output of the local shell tool call. + 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: :local_shell_call_output` + - `detail: :auto | :low | :high` - The type of the local shell tool call output. Always `local_shell_call_output`. + 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`. - - `:local_shell_call_output` + - `:auto` - - `agent: Agent{ agent_name}` + - `:low` - The agent that produced this item. + - `:high` - - `agent_name: String` + - `type: :image_file` - The canonical name of the agent that produced this item. + Always `image_file`. - - `status: :in_progress | :completed | :incomplete` + - `:image_file` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `class ImageURLContentBlock` - - `:in_progress` + References an image URL in the content of a message. - - `:completed` + - `image_url: ImageURL` - - `:incomplete` + - `url: String` - - `class ShellCall` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A tool representing a request to execute one or more shell commands. + - `detail: :auto | :low | :high` - - `action: Action{ commands, max_output_length, timeout_ms}` + 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 shell commands and limits that describe how to run the tool call. + - `:auto` - - `commands: Array[String]` + - `:low` - Ordered shell commands for the execution environment to run. + - `:high` - - `max_output_length: Integer` + - `type: :image_url` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The type of the content part. - - `timeout_ms: Integer` + - `:image_url` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `class TextContentBlock` - - `call_id: String` + The text content that is part of a message. - The unique ID of the shell tool call generated by the model. + - `text: Text` - - `type: :shell_call` + - `annotations: Array[Annotation]` - The type of the item. Always `shell_call`. + - `class FileCitationAnnotation` - - `:shell_call` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `id: String` + - `end_index: Integer` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `file_citation: FileCitation{ file_id}` - - `agent: Agent{ agent_name}` + - `file_id: String` - The agent that produced this item. + The ID of the specific File the citation is from. - - `agent_name: String` + - `start_index: Integer` - The canonical name of the agent that produced this item. + - `text: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The text in the message content that needs to be replaced. - The execution context that produced this tool call. + - `type: :file_citation` - - `class Direct` + Always `file_citation`. - - `type: :direct` + - `:file_citation` - The caller type. Always `direct`. + - `class FilePathAnnotation` - - `:direct` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `class Program` + - `end_index: Integer` - - `caller_id: String` + - `file_path: FilePath{ file_id}` - The call ID of the program item that produced this tool call. + - `file_id: String` - - `type: :program` + The ID of the file that was generated. - The caller type. Always `program`. + - `start_index: Integer` - - `:program` + - `text: String` - - `environment: BetaLocalEnvironment | BetaContainerReference` + The text in the message content that needs to be replaced. - The environment to execute the shell commands in. + - `type: :file_path` - - `class BetaLocalEnvironment` + Always `file_path`. - - `class BetaContainerReference` + - `:file_path` - - `status: :in_progress | :completed | :incomplete` + - `value: String` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The data that makes up the text. - - `:in_progress` + - `type: :text` - - `:completed` + Always `text`. - - `:incomplete` + - `:text` - - `class ShellCallOutput` + - `class RefusalContentBlock` - The streamed output items emitted by a shell tool call. + The refusal content generated by the assistant. - - `call_id: String` + - `refusal: String` - The unique ID of the shell tool call generated by the model. + - `type: :refusal` - - `output: Array[BetaResponseFunctionShellCallOutputContent]` + Always `refusal`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `:refusal` - - `outcome: Timeout{ type} | Exit{ exit_code, type}` + - `created_at: Integer` - The exit or timeout outcome associated with this shell call. + The Unix timestamp (in seconds) for when the message was created. - - `class Timeout` + - `incomplete_at: Integer` - Indicates that the shell call exceeded its configured time limit. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `type: :timeout` + - `incomplete_details: IncompleteDetails{ reason}` - The outcome type. Always `timeout`. + On an incomplete message, details about why the message is incomplete. - - `:timeout` + - `reason: :content_filter | :max_tokens | :run_cancelled | 2 more` - - `class Exit` + The reason the message is incomplete. - Indicates that the shell commands finished and returned an exit code. + - `:content_filter` - - `exit_code: Integer` + - `:max_tokens` - The exit code returned by the shell process. + - `:run_cancelled` - - `type: :exit` + - `:run_expired` - The outcome type. Always `exit`. + - `:run_failed` - - `:exit` + - `metadata: Metadata` - - `stderr: 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. - Captured stderr output for the shell call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `stdout: String` + - `object: :"thread.message"` - Captured stdout output for the shell call. + The object type, which is always `thread.message`. - - `type: :shell_call_output` + - `:"thread.message"` - The type of the item. Always `shell_call_output`. + - `role: :user | :assistant` - - `:shell_call_output` + The entity that produced the message. One of `user` or `assistant`. - - `id: String` + - `:user` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `:assistant` - - `agent: Agent{ agent_name}` + - `run_id: String` - The agent that produced this item. + 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. - - `agent_name: String` + - `status: :in_progress | :incomplete | :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`. - - `caller_: Direct{ type} | Program{ caller_id, type}` + - `:in_progress` - The execution context that produced this tool call. + - `:incomplete` - - `class Direct` + - `:completed` - - `type: :direct` + - `thread_id: String` - The caller type. Always `direct`. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `:direct` +### Message Content - - `class Program` +- `MessageContent = ImageFileContentBlock | ImageURLContentBlock | TextContentBlock | RefusalContentBlock` - - `caller_id: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The call ID of the program item that produced this tool call. + - `class ImageFileContentBlock` - - `type: :program` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The caller type. Always `program`. + - `image_file: ImageFile` - - `:program` + - `file_id: String` - - `max_output_length: Integer` + 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 maximum number of UTF-8 characters captured for this shell call's combined output. + - `detail: :auto | :low | :high` - - `status: :in_progress | :completed | :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`. - The status of the shell call output. + - `:auto` - - `:in_progress` + - `:low` - - `:completed` + - `:high` - - `:incomplete` + - `type: :image_file` - - `class ApplyPatchCall` + Always `image_file`. - A tool call representing a request to create, delete, or update files using diff patches. + - `:image_file` - - `call_id: String` + - `class ImageURLContentBlock` - The unique ID of the apply patch tool call generated by the model. + References an image URL in the content of a message. - - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + - `image_url: ImageURL` - The specific create, delete, or update instruction for the apply_patch tool call. + - `url: String` - - `class CreateFile` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Instruction for creating a new file via the apply_patch tool. + - `detail: :auto | :low | :high` - - `diff: 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` - Unified diff content to apply when creating the file. + - `:auto` - - `path: String` + - `:low` - Path of the file to create relative to the workspace root. + - `:high` - - `type: :create_file` + - `type: :image_url` - The operation type. Always `create_file`. + The type of the content part. - - `:create_file` + - `:image_url` - - `class DeleteFile` + - `class TextContentBlock` - Instruction for deleting an existing file via the apply_patch tool. + The text content that is part of a message. - - `path: String` + - `text: Text` - Path of the file to delete relative to the workspace root. + - `annotations: Array[Annotation]` - - `type: :delete_file` + - `class FileCitationAnnotation` - The operation type. Always `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. - - `:delete_file` + - `end_index: Integer` - - `class UpdateFile` + - `file_citation: FileCitation{ file_id}` - Instruction for updating an existing file via the apply_patch tool. + - `file_id: String` - - `diff: String` + The ID of the specific File the citation is from. - Unified diff content to apply to the existing file. + - `start_index: Integer` - - `path: String` + - `text: String` - Path of the file to update relative to the workspace root. + The text in the message content that needs to be replaced. - - `type: :update_file` + - `type: :file_citation` - The operation type. Always `update_file`. + Always `file_citation`. - - `:update_file` + - `:file_citation` - - `status: :in_progress | :completed` + - `class FilePathAnnotation` - The status of the apply patch tool call. One of `in_progress` or `completed`. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `:in_progress` + - `end_index: Integer` - - `:completed` + - `file_path: FilePath{ file_id}` - - `type: :apply_patch_call` + - `file_id: String` - The type of the item. Always `apply_patch_call`. + The ID of the file that was generated. - - `:apply_patch_call` + - `start_index: Integer` - - `id: String` + - `text: String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The text in the message content that needs to be replaced. - - `agent: Agent{ 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. + - `value: String` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The data that makes up the text. - The execution context that produced this tool call. + - `type: :text` - - `class Direct` + Always `text`. - - `type: :direct` + - `:text` - The caller type. Always `direct`. + - `class RefusalContentBlock` - - `:direct` + The refusal content generated by the assistant. - - `class Program` + - `refusal: String` - - `caller_id: String` + - `type: :refusal` - The call ID of the program item that produced this tool call. + Always `refusal`. - - `type: :program` + - `:refusal` - The caller type. Always `program`. +### Message Content Delta - - `:program` +- `MessageContentDelta = ImageFileDeltaBlock | TextDeltaBlock | RefusalDeltaBlock | ImageURLDeltaBlock` - - `class ApplyPatchCallOutput` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The streamed output emitted by an apply patch tool call. + - `class ImageFileDeltaBlock` - - `call_id: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The unique ID of the apply patch tool call generated by the model. + - `index: Integer` - - `status: :completed | :failed` + The index of the content part in the message. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `type: :image_file` - - `:completed` + Always `image_file`. - - `:failed` + - `:image_file` - - `type: :apply_patch_call_output` + - `image_file: ImageFileDelta` - The type of the item. Always `apply_patch_call_output`. + - `detail: :auto | :low | :high` - - `:apply_patch_call_output` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `id: String` + - `:auto` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `:low` - - `agent: Agent{ agent_name}` + - `:high` - The agent that produced this item. + - `file_id: String` - - `agent_name: 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 canonical name of the agent that produced this item. + - `class TextDeltaBlock` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The text content that is part of a message. - The execution context that produced this tool call. + - `index: Integer` - - `class Direct` + The index of the content part in the message. - - `type: :direct` + - `type: :text` - The caller type. Always `direct`. + Always `text`. - - `:direct` + - `:text` - - `class Program` + - `text: TextDelta` - - `caller_id: String` + - `annotations: Array[AnnotationDelta]` - The call ID of the program item that produced this tool call. + - `class FileCitationDeltaAnnotation` - - `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. - The caller type. Always `program`. + - `index: Integer` - - `:program` + The index of the annotation in the text content part. - - `output: String` + - `type: :file_citation` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Always `file_citation`. - - `class McpListTools` + - `:file_citation` - A list of tools available on an MCP server. + - `end_index: Integer` - - `id: String` + - `file_citation: FileCitation{ file_id, quote}` - The unique ID of the list. + - `file_id: String` - - `server_label: String` + The ID of the specific File the citation is from. - The label of the MCP server. + - `quote: String` - - `tools: Array[Tool{ input_schema, name, annotations, description}]` + The specific quote in the file. - The tools available on the server. + - `start_index: Integer` - - `input_schema: untyped` + - `text: String` - The JSON schema describing the tool's input. + The text in the message content that needs to be replaced. - - `name: String` + - `class FilePathDeltaAnnotation` - The name of the tool. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `annotations: untyped` + - `index: Integer` - Additional annotations about the tool. + The index of the annotation in the text content part. - - `description: String` + - `type: :file_path` - The description of the tool. + Always `file_path`. - - `type: :mcp_list_tools` + - `:file_path` - The type of the item. Always `mcp_list_tools`. + - `end_index: Integer` - - `:mcp_list_tools` + - `file_path: FilePath{ file_id}` - - `agent: Agent{ agent_name}` + - `file_id: String` - The agent that produced this item. + The ID of the file that was generated. - - `agent_name: String` + - `start_index: Integer` - The canonical name of the agent that produced this item. + - `text: String` - - `error: String` + The text in the message content that needs to be replaced. - Error message if the server could not list tools. + - `value: String` - - `class McpApprovalRequest` + The data that makes up the text. - A request for human approval of a tool invocation. + - `class RefusalDeltaBlock` - - `id: String` + The refusal content that is part of a message. - The unique ID of the approval request. + - `index: Integer` - - `arguments: String` + The index of the refusal part in the message. - A JSON string of arguments for the tool. + - `type: :refusal` - - `name: String` + Always `refusal`. - The name of the tool to run. + - `:refusal` - - `server_label: String` + - `refusal: String` - The label of the MCP server making the request. + - `class ImageURLDeltaBlock` - - `type: :mcp_approval_request` + References an image URL in the content of a message. - The type of the item. Always `mcp_approval_request`. + - `index: Integer` - - `:mcp_approval_request` + The index of the content part in the message. - - `agent: Agent{ agent_name}` + - `type: :image_url` - The agent that produced this item. + Always `image_url`. - - `agent_name: String` + - `:image_url` - The canonical name of the agent that produced this item. + - `image_url: ImageURLDelta` - - `class McpApprovalResponse` + - `detail: :auto | :low | :high` - A response to an MCP approval request. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `approval_request_id: String` + - `:auto` - The ID of the approval request being answered. + - `:low` - - `approve: bool` + - `:high` - Whether the request was approved. + - `url: String` - - `type: :mcp_approval_response` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the item. Always `mcp_approval_response`. +### Message Content Part Param - - `:mcp_approval_response` +- `MessageContentPartParam = ImageFileContentBlock | ImageURLContentBlock | TextContentBlockParam` - - `id: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The unique ID of the approval response + - `class ImageFileContentBlock` - - `agent: Agent{ agent_name}` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The agent that produced this item. + - `image_file: ImageFile` - - `agent_name: String` + - `file_id: String` - The canonical name of the agent that produced this item. + 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. - - `reason: String` + - `detail: :auto | :low | :high` - Optional reason for the decision. + 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`. - - `class McpCall` + - `:auto` - An invocation of a tool on an MCP server. + - `:low` - - `id: String` + - `:high` - The unique ID of the tool call. + - `type: :image_file` - - `arguments: String` + Always `image_file`. - A JSON string of the arguments passed to the tool. + - `:image_file` - - `name: String` + - `class ImageURLContentBlock` - The name of the tool that was run. + References an image URL in the content of a message. - - `server_label: String` + - `image_url: ImageURL` - The label of the MCP server running the tool. + - `url: String` - - `type: :mcp_call` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the item. Always `mcp_call`. + - `detail: :auto | :low | :high` - - `:mcp_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` - - `agent: Agent{ 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` - - `approval_request_id: String` + The type of the content part. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `:image_url` - - `error: String` + - `class TextContentBlockParam` - The error from the tool call, if any. + The text content that is part of a message. - - `output: String` + - `text: String` - The output from the tool call. + Text content to be sent to the model - - `status: :in_progress | :completed | :incomplete | 2 more` + - `type: :text` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Always `text`. - - `:in_progress` + - `:text` - - `:completed` +### Message Deleted - - `:incomplete` +- `class MessageDeleted` - - `:calling` + - `id: String` - - `:failed` + - `deleted: bool` - - `class BetaResponseCustomToolCallOutput` + - `object: :"thread.message.deleted"` - The output of a custom tool call from your code, being sent back to the model. + - `:"thread.message.deleted"` - - `call_id: String` +### Message Delta - The call ID, used to map this custom tool call output to a custom tool call. +- `class MessageDelta` - - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + The delta containing the fields that have changed on the Message. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `content: Array[MessageContentDelta]` - - `String = String` + The content of the message in array of text and/or images. - A string of the output of the custom tool call. + - `class ImageFileDeltaBlock` - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Text, image, or file output of the custom tool call. + - `index: Integer` - - `class BetaResponseInputText` + The index of the content part in the message. - A text input to the model. + - `type: :image_file` - - `class BetaResponseInputImage` + Always `image_file`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `:image_file` - - `class BetaResponseInputFile` + - `image_file: ImageFileDelta` - A file input to the model. + - `detail: :auto | :low | :high` - - `type: :custom_tool_call_output` + 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 type of the custom tool call output. Always `custom_tool_call_output`. + - `:auto` - - `:custom_tool_call_output` + - `:low` - - `id: String` + - `:high` - The unique ID of the custom tool call output in the OpenAI platform. + - `file_id: String` - - `agent: Agent{ agent_name}` + 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 agent that produced this item. + - `class TextDeltaBlock` - - `agent_name: String` + The text content that is part of a message. - The canonical name of the agent that produced this item. + - `index: Integer` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The index of the content part in the message. - The execution context that produced this tool call. + - `type: :text` - - `class Direct` + Always `text`. - - `type: :direct` + - `:text` - The caller type. Always `direct`. + - `text: TextDelta` - - `:direct` + - `annotations: Array[AnnotationDelta]` - - `class Program` + - `class FileCitationDeltaAnnotation` - - `caller_id: String` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The call ID of the program item that produced this tool call. + - `index: Integer` - - `type: :program` + The index of the annotation in the text content part. - The caller type. Always `program`. + - `type: :file_citation` - - `:program` + Always `file_citation`. - - `class BetaResponseCustomToolCall` + - `:file_citation` - A call to a custom tool created by the model. + - `end_index: Integer` - - `call_id: String` + - `file_citation: FileCitation{ file_id, quote}` - An identifier used to map this custom tool call to a tool call output. + - `file_id: String` - - `input: String` + The ID of the specific File the citation is from. - The input for the custom tool call generated by the model. + - `quote: String` - - `name: String` + The specific quote in the file. - The name of the custom tool being called. + - `start_index: Integer` - - `type: :custom_tool_call` + - `text: String` - The type of the custom tool call. Always `custom_tool_call`. + The text in the message content that needs to be replaced. - - `:custom_tool_call` + - `class FilePathDeltaAnnotation` - - `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 custom tool call in the OpenAI platform. + - `index: Integer` - - `agent: Agent{ agent_name}` + The index of the annotation in the text content part. - 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_: Direct{ type} | Program{ caller_id, type}` + - `end_index: Integer` - The execution context that produced this tool call. + - `file_path: FilePath{ file_id}` - - `class Direct` + - `file_id: String` - - `type: :direct` + The ID of the file that was generated. - - `:direct` + - `start_index: Integer` - - `class Program` + - `text: String` - - `caller_id: String` + The text in the message content that needs to be replaced. - The call ID of the program item that produced this tool call. + - `value: String` - - `type: :program` + The data that makes up the text. - - `:program` + - `class RefusalDeltaBlock` - - `namespace: String` + The refusal content that is part of a message. - The namespace of the custom tool being called. + - `index: Integer` - - `class CompactionTrigger` + The index of the refusal part in the message. - Compacts the current context. Must be the final input item. + - `type: :refusal` - - `type: :compaction_trigger` + Always `refusal`. - The type of the item. Always `compaction_trigger`. + - `:refusal` - - `:compaction_trigger` + - `refusal: String` - - `agent: Agent{ agent_name}` + - `class ImageURLDeltaBlock` - The agent that produced this item. + References an image URL in the content of a message. - - `agent_name: String` + - `index: Integer` - The canonical name of the agent that produced this item. + The index of the content part in the message. - - `class ItemReference` + - `type: :image_url` - An internal identifier for an item to reference. + Always `image_url`. - - `id: String` + - `:image_url` - The ID of the item to reference. + - `image_url: ImageURLDelta` - - `agent: Agent{ agent_name}` + - `detail: :auto | :low | :high` - The agent that produced this item. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `agent_name: String` + - `:auto` - The canonical name of the agent that produced this item. + - `:low` - - `type: :item_reference` + - `:high` - The type of item to reference. Always `item_reference`. + - `url: String` - - `:item_reference` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `class Program` + - `role: :user | :assistant` - - `id: String` + The entity that produced the message. One of `user` or `assistant`. - The unique ID of this program item. + - `:user` - - `call_id: String` + - `:assistant` - The stable call ID of the program item. +### Message Delta Event - - `code: String` +- `class MessageDeltaEvent` - The JavaScript source executed by programmatic tool calling. + Represents a message delta i.e. any changed fields on a message during streaming. - - `fingerprint: String` + - `id: String` - Opaque program replay fingerprint that must be round-tripped. + The identifier of the message, which can be referenced in API endpoints. - - `type: :program` + - `delta: MessageDelta` - The item type. Always `program`. + The delta containing the fields that have changed on the Message. - - `:program` + - `content: Array[MessageContentDelta]` - - `agent: Agent{ agent_name}` + The content of the message in array of text and/or images. - The agent that produced this item. + - `class ImageFileDeltaBlock` - - `agent_name: String` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The canonical name of the agent that produced this item. + - `index: Integer` - - `class ProgramOutput` + The index of the content part in the message. - - `id: String` + - `type: :image_file` - The unique ID of this program output item. + Always `image_file`. - - `call_id: String` + - `:image_file` - The call ID of the program item. + - `image_file: ImageFileDelta` - - `result: String` + - `detail: :auto | :low | :high` - The result produced by the program item. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `status: :completed | :incomplete` + - `:auto` - The terminal status of the program output. + - `:low` - - `:completed` + - `:high` - - `:incomplete` + - `file_id: String` - - `type: :program_output` + 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 item type. Always `program_output`. + - `class TextDeltaBlock` - - `:program_output` + The text content that is part of a message. - - `agent: Agent{ agent_name}` + - `index: Integer` - The agent that produced this item. + The index of the content part in the message. - - `agent_name: String` + - `type: :text` - The canonical name of the agent that produced this item. + Always `text`. -- `instructions: String` + - `:text` - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - `text: TextDelta` -- `model: String` + - `annotations: Array[AnnotationDelta]` - 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. + - `class FileCitationDeltaAnnotation` -- `parallel_tool_calls: bool` + 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. - Whether to allow the model to run tool calls in parallel. + - `index: Integer` -- `personality: String | :friendly | :pragmatic` + The index of the annotation in the text content part. - A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + - `type: :file_citation` - - `String = String` + Always `file_citation`. - - `Personality = :friendly | :pragmatic` + - `:file_citation` - 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. + - `end_index: Integer` - - `:friendly` + - `file_citation: FileCitation{ file_id, quote}` - - `:pragmatic` + - `file_id: String` -- `previous_response_id: String` + The ID of the specific File the citation is from. - 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`. + - `quote: String` -- `reasoning: Reasoning{ context, effort, generate_summary, 2 more}` + The specific quote in the file. - **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `start_index: Integer` - - `context: :auto | :current_turn | :all_turns` + - `text: 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 text in the message content that needs to be replaced. - - `:auto` + - `class FilePathDeltaAnnotation` - - `:current_turn` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `:all_turns` + - `index: Integer` - - `effort: :none | :minimal | :low | 4 more` + The index of the annotation in the text content part. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `type: :file_path` - - `:none` + Always `file_path`. - - `:minimal` + - `:file_path` - - `:low` + - `end_index: Integer` - - `:medium` + - `file_path: FilePath{ file_id}` - - `:high` + - `file_id: String` - - `:xhigh` + The ID of the file that was generated. - - `:max` + - `start_index: Integer` - - `generate_summary: :auto | :concise | :detailed` + - `text: String` - **Deprecated:** use `summary` instead. + 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`. + - `value: String` - - `:auto` + The data that makes up the text. - - `:concise` + - `class RefusalDeltaBlock` - - `:detailed` + The refusal content that is part of a message. - - `mode: String | :standard | :pro` + - `index: Integer` - Controls the reasoning execution mode for the request. + The index of the refusal part in the message. - When returned on a response, this is the effective execution mode. + - `type: :refusal` - - `String = String` + Always `refusal`. - - `Mode = :standard | :pro` + - `:refusal` - Controls the reasoning execution mode for the request. + - `refusal: String` - When returned on a response, this is the effective execution mode. + - `class ImageURLDeltaBlock` - - `:standard` + References an image URL in the content of a message. - - `:pro` + - `index: Integer` - - `summary: :auto | :concise | :detailed` + The index of the content part in the 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`. + - `type: :image_url` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + Always `image_url`. - - `:auto` + - `:image_url` - - `:concise` + - `image_url: ImageURLDelta` - - `:detailed` + - `detail: :auto | :low | :high` -- `text: Text{ format_, verbosity}` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `:auto` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `:low` - - `format_: BetaResponseFormatTextConfig` + - `:high` - An object specifying the format that the model must output. + - `url: 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 URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The default format is `{ "type": "text" }` with no additional options. + - `role: :user | :assistant` - **Not recommended for gpt-4o and newer models:** + The entity that produced the message. One of `user` or `assistant`. - 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. + - `:user` - - `class Text` + - `:assistant` - Default response format. Used to generate text responses. + - `object: :"thread.message.delta"` - - `type: :text` + The object type, which is always `thread.message.delta`. - The type of response format being defined. Always `text`. + - `:"thread.message.delta"` - - `:text` +### Refusal Content Block - - `class BetaResponseFormatTextJSONSchemaConfig` +- `class RefusalContentBlock` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The refusal content generated by the assistant. - - `name: String` + - `refusal: 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. + - `type: :refusal` - - `schema: Hash[Symbol, untyped]` + 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` +### Refusal Delta Block - The type of response format being defined. Always `json_schema`. +- `class RefusalDeltaBlock` - - `:json_schema` + The refusal content that is part of a message. - - `description: String` + - `index: Integer` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The index of the refusal part in the message. - - `strict: bool` + - `type: :refusal` - 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 `refusal`. - - `class JSONObject` + - `:refusal` - 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. + - `refusal: String` - - `type: :json_object` +### Text - The type of response format being defined. Always `json_object`. +- `class Text` - - `:json_object` + - `annotations: Array[Annotation]` - - `verbosity: :low | :medium | :high` + - `class FileCitationAnnotation` - 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`. + 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` + - `end_index: Integer` - - `:medium` + - `file_citation: FileCitation{ file_id}` - - `:high` + - `file_id: String` -- `tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | 6 more` + The ID of the specific File the citation is from. - Controls which tool the model should use, if any. + - `start_index: Integer` - - `BetaToolChoiceOptions = :none | :auto | :required` + - `text: String` - Controls which (if any) tool is called by the model. + The text in the message content that needs to be replaced. - `none` means the model will not call any tool and instead generates a message. + - `type: :file_citation` - `auto` means the model can pick between generating a message or calling one or - more tools. + Always `file_citation`. - `required` means the model must call one or more tools. + - `:file_citation` - - `:none` + - `class FilePathAnnotation` - - `:auto` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `:required` + - `end_index: Integer` - - `class BetaToolChoiceAllowed` + - `file_path: FilePath{ file_id}` - Constrains the tools available to the model to a pre-defined set. + - `file_id: String` - - `mode: :auto | :required` + The ID of the file that was generated. - Constrains the tools available to the model to a pre-defined set. + - `start_index: Integer` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `text: String` - `required` requires the model to call one or more of the allowed tools. + The text in the message content that needs to be replaced. - - `:auto` + - `type: :file_path` - - `:required` + Always `file_path`. - - `tools: Array[Hash[Symbol, untyped]]` + - `:file_path` - A list of tool definitions that the model should be allowed to call. + - `value: String` - For the Responses API, the list of tool definitions might look like: + The data that makes up the text. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` +### Text Content Block - - `type: :allowed_tools` +- `class TextContentBlock` - Allowed tool configuration type. Always `allowed_tools`. + The text content that is part of a message. - - `:allowed_tools` + - `text: Text` - - `class BetaToolChoiceTypes` + - `annotations: Array[Annotation]` - 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). + - `class FileCitationAnnotation` - - `type: :file_search | :web_search_preview | :computer | 5 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. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `end_index: Integer` - Allowed values are: + - `file_citation: FileCitation{ file_id}` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `file_id: String` - - `:file_search` + The ID of the specific File the citation is from. - - `:web_search_preview` + - `start_index: Integer` - - `:computer` + - `text: String` - - `:computer_use_preview` + The text in the message content that needs to be replaced. - - `:computer_use` + - `type: :file_citation` - - `:web_search_preview_2025_03_11` + Always `file_citation`. - - `:image_generation` + - `:file_citation` - - `:code_interpreter` + - `class FilePathAnnotation` - - `class BetaToolChoiceFunction` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Use this option to force the model to call a specific function. + - `end_index: Integer` - - `name: String` + - `file_path: FilePath{ file_id}` - The name of the function to call. + - `file_id: String` - - `type: :function` + The ID of the file that was generated. - For function calling, the type is always `function`. + - `start_index: Integer` - - `:function` + - `text: String` - - `class BetaToolChoiceMcp` + The text in the message content that needs to be replaced. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: :file_path` - - `server_label: String` + Always `file_path`. - The label of the MCP server to use. + - `:file_path` - - `type: :mcp` + - `value: String` - For MCP tools, the type is always `mcp`. + The data that makes up the text. - - `:mcp` + - `type: :text` - - `name: String` + Always `text`. - The name of the tool to call on the server. + - `:text` - - `class BetaToolChoiceCustom` +### Text Content Block Param - Use this option to force the model to call a specific custom tool. +- `class TextContentBlockParam` - - `name: String` + The text content that is part of a message. - The name of the custom tool to call. + - `text: String` - - `type: :custom` + Text content to be sent to the model - For custom tool calling, the type is always `custom`. + - `type: :text` - - `:custom` + Always `text`. - - `class BetaSpecificProgrammaticToolCallingParam` + - `:text` - - `type: :programmatic_tool_calling` +### Text Delta - The tool to call. Always `programmatic_tool_calling`. +- `class TextDelta` - - `:programmatic_tool_calling` + - `annotations: Array[AnnotationDelta]` - - `class BetaToolChoiceApplyPatch` + - `class FileCitationDeltaAnnotation` - Forces the model to call the apply_patch tool when executing a tool call. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `type: :apply_patch` + - `index: Integer` - The tool to call. Always `apply_patch`. + The index of the annotation in the text content part. - - `:apply_patch` + - `type: :file_citation` - - `class BetaToolChoiceShell` + Always `file_citation`. - Forces the model to call the shell tool when a tool call is required. + - `:file_citation` - - `type: :shell` + - `end_index: Integer` - The tool to call. Always `shell`. + - `file_citation: FileCitation{ file_id, quote}` - - `:shell` + - `file_id: String` -- `tools: Array[BetaTool]` + The ID of the specific File the citation is from. - 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. + - `quote: String` - - `class BetaFunctionTool` + The specific quote in 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). + - `start_index: Integer` - - `class BetaFileSearchTool` + - `text: String` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The text in the message content that needs to be replaced. - - `class BetaComputerTool` + - `class FilePathDeltaAnnotation` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `class BetaComputerUsePreviewTool` + - `index: Integer` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the annotation in the text content part. - - `class BetaWebSearchTool` + - `type: :file_path` - 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). + Always `file_path`. - - `class Mcp` + - `:file_path` - 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). + - `end_index: Integer` - - `class CodeInterpreter` + - `file_path: FilePath{ file_id}` - A tool that runs Python code to help generate a response to a prompt. + - `file_id: String` - - `class ProgrammaticToolCalling` + The ID of the file that was generated. - - `class ImageGeneration` + - `start_index: Integer` - A tool that generates images using the GPT image models. + - `text: String` - - `class LocalShell` + The text in the message content that needs to be replaced. - A tool that allows the model to execute shell commands in a local environment. + - `value: String` - - `class BetaFunctionShellTool` + The data that makes up the text. - A tool that allows the model to execute shell commands. +### Text Delta Block - - `class BetaCustomTool` +- `class TextDeltaBlock` - 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 text content that is part of a message. - - `class BetaNamespaceTool` + - `index: Integer` - Groups function/custom tools under a shared namespace. + The index of the content part in the message. - - `class BetaToolSearchTool` + - `type: :text` - Hosted or BYOT tool search configuration for deferred tools. + Always `text`. - - `class BetaWebSearchPreviewTool` + - `: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). + - `text: TextDelta` - - `class BetaApplyPatchTool` + - `annotations: Array[AnnotationDelta]` - Allows the assistant to create, delete, or update files using unified diffs. + - `class FileCitationDeltaAnnotation` -- `truncation: :auto | :disabled` + 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 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. + - `index: Integer` - - `:auto` + The index of the annotation in the text content part. - - `:disabled` + - `type: :file_citation` -- `betas: Array[:"responses_multi_agent=v1"]` + Always `file_citation`. - - `:"responses_multi_agent=v1"` + - `:file_citation` -### Returns + - `end_index: Integer` -- `class InputTokenCountResponse` + - `file_citation: FileCitation{ file_id, quote}` - - `input_tokens: Integer` + - `file_id: String` - - `object: :"response.input_tokens"` + The ID of the specific File the citation is from. - - `:"response.input_tokens"` + - `quote: String` -### Example + The specific quote in the file. -```ruby -require "openai" + - `start_index: Integer` -openai = OpenAI::Client.new(api_key: "My API Key") + - `text: String` -response = openai.beta.responses.input_tokens.count + The text in the message content that needs to be replaced. -puts(response) -``` + - `class FilePathDeltaAnnotation` -#### Response + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -```json -{ - "input_tokens": 123, - "object": "response.input_tokens" -} -``` + - `index: Integer` -### Example + The index of the annotation in the text content part. -```ruby -require "openai" + - `type: :file_path` -openai = OpenAI::Client.new + Always `file_path`. -response = openai.responses.input_tokens.count(model: "gpt-5", input: "Tell me a joke.") + - `:file_path` -puts(response) -``` + - `end_index: Integer` -#### Response + - `file_path: FilePath{ file_id}` -```json -{ - "object": "response.input_tokens", - "input_tokens": 11 -} -``` + - `file_id: String` -## Domain Types + The ID of the file that was generated. -### Input Token Count Response + - `start_index: Integer` -- `class InputTokenCountResponse` + - `text: String` - - `input_tokens: Integer` + The text in the message content that needs to be replaced. - - `object: :"response.input_tokens"` + - `value: String` - - `:"response.input_tokens"` + The data that makes up the text.