diff --git a/en/ruby/resources/conversations/index.md b/en/ruby/resources/conversations/index.md deleted file mode 100644 index 5ed6e57..0000000 --- a/en/ruby/resources/conversations/index.md +++ /dev/null @@ -1,21522 +0,0 @@ -# Conversations - -## Create a conversation - -`conversations.create(**kwargs) -> Conversation` - -**post** `/conversations` - -Create a conversation. - -### Parameters - -- `items: Array[ResponseInputItem]` - - Initial items to include in the conversation context. You may add up to 20 items at a time. - - - `class EasyInputMessage` - - 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 | ResponseInputMessageContentList` - - 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. - - - `ResponseInputMessageContentList = Array[ResponseInputContent]` - - A list of one or many input items to the model, containing different content - types. - - - `class ResponseInputText` - - 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` - - - `class ResponseInputImage` - - 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. - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `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: ResponseInputMessageContentList` - - 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` - - - `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 ResponseOutputMessage` - - An output message from the model. - - - `id: String` - - The unique ID of the output message. - - - `content: Array[ResponseOutputText | ResponseOutputRefusal]` - - The content of the output message. - - - `class ResponseOutputText` - - 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 ResponseOutputRefusal` - - 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` - - - `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 ResponseFileSearchToolCall` - - 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` - - - `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 ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ComputerCallOutput` - - The output of a computer tool call. - - - `call_id: String` - - The ID of the computer tool call that produced the output. - - - `output: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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. - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `class ResponseFunctionToolCall` - - 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. - - - `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 | ResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `String = String` - - A JSON string of the output of the function tool call. - - - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]` - - An array of content outputs (text, image, file) for the function tool call. - - - `class ResponseInputTextContent` - - 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` - - - `class ResponseInputImageContent` - - 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. - - - `class ResponseInputFileContent` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `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. - - - `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 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. - - - `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 ResponseToolSearchOutputItemParam` - - - `tools: Array[Tool]` - - The loaded tool definitions returned by the tool search output. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The item type. Always `tool_search_output`. - - - `:tool_search_output` - - - `id: String` - - The unique ID of this tool search output. - - - `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 ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItemParam` - - 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. - - - `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` - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `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. - - - `environment: LocalEnvironment | ContainerReference` - - The environment to execute the shell commands in. - - - `class LocalEnvironment` - - - `class ContainerReference` - - - `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[ResponseFunctionShellCallOutputContent]` - - 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. - - - `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. - - - `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. - - - `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` - - - `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` - - - `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 - - - `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` - - - `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 ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - - - `class ResponseCustomToolCall` - - 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. - - - `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` - - - `class ItemReference` - - An internal identifier for an item to reference. - - - `id: String` - - The ID of the item to reference. - - - `type: :item_reference` - - The type of item to reference. Always `item_reference`. - - - `:item_reference` - -- `metadata: Metadata` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - -### Returns - -- `class Conversation` - - - `id: String` - - The unique ID of the conversation. - - - `created_at: Integer` - - The time at which the conversation was created, measured in seconds since the Unix epoch. - - - `metadata: untyped` - - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - - `object: :conversation` - - The object type, which is always `conversation`. - - - `:conversation` - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation = openai.conversations.create - -puts(conversation) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` - -## Retrieve a conversation - -`conversations.retrieve(conversation_id) -> Conversation` - -**get** `/conversations/{conversation_id}` - -Get a conversation - -### Parameters - -- `conversation_id: String` - -### Returns - -- `class Conversation` - - - `id: String` - - The unique ID of the conversation. - - - `created_at: Integer` - - The time at which the conversation was created, measured in seconds since the Unix epoch. - - - `metadata: untyped` - - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - - `object: :conversation` - - The object type, which is always `conversation`. - - - `:conversation` - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation = openai.conversations.retrieve("conv_123") - -puts(conversation) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` - -## Update a conversation - -`conversations.update(conversation_id, **kwargs) -> Conversation` - -**post** `/conversations/{conversation_id}` - -Update a conversation - -### Parameters - -- `conversation_id: String` - -- `metadata: Metadata` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - -### Returns - -- `class Conversation` - - - `id: String` - - The unique ID of the conversation. - - - `created_at: Integer` - - The time at which the conversation was created, measured in seconds since the Unix epoch. - - - `metadata: untyped` - - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - - `object: :conversation` - - The object type, which is always `conversation`. - - - `:conversation` - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation = openai.conversations.update("conv_123", metadata: {foo: "string"}) - -puts(conversation) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` - -## Delete a conversation - -`conversations.delete(conversation_id) -> ConversationDeletedResource` - -**delete** `/conversations/{conversation_id}` - -Delete a conversation. Items in the conversation will not be deleted. - -### Parameters - -- `conversation_id: String` - -### Returns - -- `class ConversationDeletedResource` - - - `id: String` - - - `deleted: bool` - - - `object: :"conversation.deleted"` - - - `:"conversation.deleted"` - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation_deleted_resource = openai.conversations.delete("conv_123") - -puts(conversation_deleted_resource) -``` - -#### Response - -```json -{ - "id": "id", - "deleted": true, - "object": "conversation.deleted" -} -``` - -## Domain Types - -### Computer Screenshot Content - -- `class ComputerScreenshotContent` - - 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` - -### Conversation - -- `class Conversation` - - - `id: String` - - The unique ID of the conversation. - - - `created_at: Integer` - - The time at which the conversation was created, measured in seconds since the Unix epoch. - - - `metadata: untyped` - - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - - `object: :conversation` - - The object type, which is always `conversation`. - - - `:conversation` - -### Conversation Deleted - -- `class ConversationDeleted` - - - `id: String` - - - `deleted: bool` - - - `object: :"conversation.deleted"` - - - `:"conversation.deleted"` - -### Conversation Deleted Resource - -- `class ConversationDeletedResource` - - - `id: String` - - - `deleted: bool` - - - `object: :"conversation.deleted"` - - - `:"conversation.deleted"` - -### Message - -- `class Message` - - A message to or from the model. - - - `id: String` - - The unique ID of the message. - - - `content: Array[ResponseInputText | ResponseOutputText | TextContent | 6 more]` - - The content of the message - - - `class ResponseInputText` - - 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` - - - `class ResponseOutputText` - - 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 TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - - - `class SummaryTextContent` - - 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 ResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `class ResponseInputImage` - - 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. - - - `class ComputerScreenshotContent` - - 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` - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `role: :unknown | :user | :assistant | 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `status: :in_progress | :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. Always set to `message`. - - - `:message` - - - `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` - -### Summary Text Content - -- `class SummaryTextContent` - - A summary text from the model. - - - `text: String` - - A summary of the reasoning output from the model so far. - - - `type: :summary_text` - - The type of the object. Always `summary_text`. - - - `:summary_text` - -### Text Content - -- `class TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - -# Items - -## Create items - -`conversations.items.create(conversation_id, **kwargs) -> ConversationItemList` - -**post** `/conversations/{conversation_id}/items` - -Create items in a conversation with the given ID. - -### Parameters - -- `conversation_id: String` - -- `items: Array[ResponseInputItem]` - - The items to add to the conversation. You may add up to 20 items at a time. - - - `class EasyInputMessage` - - 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 | ResponseInputMessageContentList` - - 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. - - - `ResponseInputMessageContentList = Array[ResponseInputContent]` - - A list of one or many input items to the model, containing different content - types. - - - `class ResponseInputText` - - 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` - - - `class ResponseInputImage` - - 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. - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `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: ResponseInputMessageContentList` - - 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` - - - `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 ResponseOutputMessage` - - An output message from the model. - - - `id: String` - - The unique ID of the output message. - - - `content: Array[ResponseOutputText | ResponseOutputRefusal]` - - The content of the output message. - - - `class ResponseOutputText` - - 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 ResponseOutputRefusal` - - 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` - - - `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 ResponseFileSearchToolCall` - - 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` - - - `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 ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ComputerCallOutput` - - The output of a computer tool call. - - - `call_id: String` - - The ID of the computer tool call that produced the output. - - - `output: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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. - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `class ResponseFunctionToolCall` - - 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. - - - `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 | ResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `String = String` - - A JSON string of the output of the function tool call. - - - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]` - - An array of content outputs (text, image, file) for the function tool call. - - - `class ResponseInputTextContent` - - 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` - - - `class ResponseInputImageContent` - - 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. - - - `class ResponseInputFileContent` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `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. - - - `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 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. - - - `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 ResponseToolSearchOutputItemParam` - - - `tools: Array[Tool]` - - The loaded tool definitions returned by the tool search output. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The item type. Always `tool_search_output`. - - - `:tool_search_output` - - - `id: String` - - The unique ID of this tool search output. - - - `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 ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItemParam` - - 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. - - - `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` - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `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. - - - `environment: LocalEnvironment | ContainerReference` - - The environment to execute the shell commands in. - - - `class LocalEnvironment` - - - `class ContainerReference` - - - `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[ResponseFunctionShellCallOutputContent]` - - 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. - - - `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. - - - `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. - - - `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` - - - `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` - - - `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 - - - `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` - - - `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 ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - - - `class ResponseCustomToolCall` - - 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. - - - `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` - - - `class ItemReference` - - An internal identifier for an item to reference. - - - `id: String` - - The ID of the item to reference. - - - `type: :item_reference` - - The type of item to reference. Always `item_reference`. - - - `:item_reference` - -- `include: Array[ResponseIncludable]` - - Additional fields to include in the response. See the `include` - parameter for [listing Conversation items above](https://platform.openai.com/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. - - - `:"file_search_call.results"` - - - `:"web_search_call.results"` - - - `:"web_search_call.action.sources"` - - - `:"message.input_image.image_url"` - - - `:"computer_call_output.output.image_url"` - - - `:"code_interpreter_call.outputs"` - - - `:"reasoning.encrypted_content"` - - - `:"message.output_text.logprobs"` - -### Returns - -- `class ConversationItemList` - - A list of Conversation items. - - - `data: Array[ConversationItem]` - - A list of conversation items. - - - `class Message` - - A message to or from the model. - - - `id: String` - - The unique ID of the message. - - - `content: Array[ResponseInputText | ResponseOutputText | TextContent | 6 more]` - - The content of the message - - - `class ResponseInputText` - - 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` - - - `class ResponseOutputText` - - 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 TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - - - `class SummaryTextContent` - - 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 ResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `class ResponseInputImage` - - 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. - - - `class ComputerScreenshotContent` - - 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` - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `role: :unknown | :user | :assistant | 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `status: :in_progress | :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. Always set to `message`. - - - `:message` - - - `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 ResponseFunctionToolCallItem` - - 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` - - The unique ID of the function tool call. - - - `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 ResponseFunctionToolCallOutputItem` - - - `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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the function call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseFileSearchToolCall` - - 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` - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `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` - - - `class ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ResponseComputerToolCallOutputItem` - - - `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: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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}]` - - 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. - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchCall` - - - `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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchOutputItem` - - - `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[Tool]` - - The loaded tool definitions returned by tool search. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The type of the item. Always `tool_search_output`. - - - `:tool_search_output` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItem` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ResponseFunctionShellToolCall` - - 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: ResponseLocalEnvironment | ResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class ResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class ResponseContainerReference` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseFunctionShellToolCallOutput` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseApplyPatchToolCall` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseApplyPatchToolCallOutput` - - 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` - - - `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 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` - - - `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` - - - `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` - - - `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` - - - `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 ResponseCustomToolCall` - - 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. - - - `namespace: String` - - The namespace of the custom tool being called. - - - `class ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - - - `first_id: String` - - The ID of the first item in the list. - - - `has_more: bool` - - Whether there are more items available. - - - `last_id: String` - - The ID of the last item in the list. - - - `object: :list` - - The type of object returned, must be `list`. - - - `:list` - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation_item_list = openai.conversations.items.create("conv_123", items: [{content: "string", role: :user, type: :message}]) - -puts(conversation_item_list) -``` - -#### Response - -```json -{ - "data": [ - { - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "role": "unknown", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` - -## List items - -`conversations.items.list(conversation_id, **kwargs) -> ConversationCursorPage` - -**get** `/conversations/{conversation_id}/items` - -List all items for a conversation with the given ID. - -### Parameters - -- `conversation_id: String` - -- `after: String` - - An item ID to list items after, used in pagination. - -- `include: Array[ResponseIncludable]` - - Specify additional output data to include in the model response. Currently supported values are: - - - `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). - - - `:"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"` - -- `limit: Integer` - - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. - -- `order: :asc | :desc` - - The order to return the input items in. Default is `desc`. - - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. - - - `:asc` - - - `:desc` - -### Returns - -- `ConversationItem = Message | ResponseFunctionToolCallItem | ResponseFunctionToolCallOutputItem | 22 more` - - A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output). - - - `class Message` - - A message to or from the model. - - - `id: String` - - The unique ID of the message. - - - `content: Array[ResponseInputText | ResponseOutputText | TextContent | 6 more]` - - The content of the message - - - `class ResponseInputText` - - 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` - - - `class ResponseOutputText` - - 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 TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - - - `class SummaryTextContent` - - 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 ResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `class ResponseInputImage` - - 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. - - - `class ComputerScreenshotContent` - - 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` - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `role: :unknown | :user | :assistant | 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `status: :in_progress | :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. Always set to `message`. - - - `:message` - - - `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 ResponseFunctionToolCallItem` - - 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` - - The unique ID of the function tool call. - - - `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 ResponseFunctionToolCallOutputItem` - - - `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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the function call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseFileSearchToolCall` - - 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` - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `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` - - - `class ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ResponseComputerToolCallOutputItem` - - - `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: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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}]` - - 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. - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchCall` - - - `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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchOutputItem` - - - `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[Tool]` - - The loaded tool definitions returned by tool search. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The type of the item. Always `tool_search_output`. - - - `:tool_search_output` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItem` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ResponseFunctionShellToolCall` - - 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: ResponseLocalEnvironment | ResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class ResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class ResponseContainerReference` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseFunctionShellToolCallOutput` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseApplyPatchToolCall` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseApplyPatchToolCallOutput` - - 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` - - - `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 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` - - - `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` - - - `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` - - - `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` - - - `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 ResponseCustomToolCall` - - 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. - - - `namespace: String` - - The namespace of the custom tool being called. - - - `class ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -page = openai.conversations.items.list("conv_123") - -puts(page) -``` - -#### Response - -```json -{ - "data": [ - { - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "role": "unknown", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` - -## Retrieve an item - -`conversations.items.retrieve(item_id, **kwargs) -> ConversationItem` - -**get** `/conversations/{conversation_id}/items/{item_id}` - -Get a single item from a conversation with the given IDs. - -### Parameters - -- `conversation_id: String` - -- `item_id: String` - -- `include: Array[ResponseIncludable]` - - Additional fields to include in the response. See the `include` - parameter for [listing Conversation items above](https://platform.openai.com/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. - - - `:"file_search_call.results"` - - - `:"web_search_call.results"` - - - `:"web_search_call.action.sources"` - - - `:"message.input_image.image_url"` - - - `:"computer_call_output.output.image_url"` - - - `:"code_interpreter_call.outputs"` - - - `:"reasoning.encrypted_content"` - - - `:"message.output_text.logprobs"` - -### Returns - -- `ConversationItem = Message | ResponseFunctionToolCallItem | ResponseFunctionToolCallOutputItem | 22 more` - - A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output). - - - `class Message` - - A message to or from the model. - - - `id: String` - - The unique ID of the message. - - - `content: Array[ResponseInputText | ResponseOutputText | TextContent | 6 more]` - - The content of the message - - - `class ResponseInputText` - - 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` - - - `class ResponseOutputText` - - 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 TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - - - `class SummaryTextContent` - - 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 ResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `class ResponseInputImage` - - 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. - - - `class ComputerScreenshotContent` - - 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` - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `role: :unknown | :user | :assistant | 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `status: :in_progress | :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. Always set to `message`. - - - `:message` - - - `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 ResponseFunctionToolCallItem` - - 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` - - The unique ID of the function tool call. - - - `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 ResponseFunctionToolCallOutputItem` - - - `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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the function call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseFileSearchToolCall` - - 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` - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `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` - - - `class ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ResponseComputerToolCallOutputItem` - - - `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: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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}]` - - 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. - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchCall` - - - `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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchOutputItem` - - - `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[Tool]` - - The loaded tool definitions returned by tool search. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The type of the item. Always `tool_search_output`. - - - `:tool_search_output` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItem` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ResponseFunctionShellToolCall` - - 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: ResponseLocalEnvironment | ResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class ResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class ResponseContainerReference` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseFunctionShellToolCallOutput` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseApplyPatchToolCall` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseApplyPatchToolCallOutput` - - 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` - - - `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 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` - - - `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` - - - `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` - - - `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` - - - `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 ResponseCustomToolCall` - - 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. - - - `namespace: String` - - The namespace of the custom tool being called. - - - `class ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation_item = openai.conversations.items.retrieve("msg_abc", conversation_id: "conv_123") - -puts(conversation_item) -``` - -#### Response - -```json -{ - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "role": "unknown", - "status": "in_progress", - "type": "message", - "phase": "commentary" -} -``` - -## Delete an item - -`conversations.items.delete(item_id, **kwargs) -> Conversation` - -**delete** `/conversations/{conversation_id}/items/{item_id}` - -Delete an item from a conversation with the given IDs. - -### Parameters - -- `conversation_id: String` - -- `item_id: String` - -### Returns - -- `class Conversation` - - - `id: String` - - The unique ID of the conversation. - - - `created_at: Integer` - - The time at which the conversation was created, measured in seconds since the Unix epoch. - - - `metadata: untyped` - - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - - `object: :conversation` - - The object type, which is always `conversation`. - - - `:conversation` - -### Example - -```ruby -require "openai" - -openai = OpenAI::Client.new(api_key: "My API Key") - -conversation = openai.conversations.items.delete("msg_abc", conversation_id: "conv_123") - -puts(conversation) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` - -## Domain Types - -### Conversation Item - -- `ConversationItem = Message | ResponseFunctionToolCallItem | ResponseFunctionToolCallOutputItem | 22 more` - - A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output). - - - `class Message` - - A message to or from the model. - - - `id: String` - - The unique ID of the message. - - - `content: Array[ResponseInputText | ResponseOutputText | TextContent | 6 more]` - - The content of the message - - - `class ResponseInputText` - - 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` - - - `class ResponseOutputText` - - 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 TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - - - `class SummaryTextContent` - - 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 ResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `class ResponseInputImage` - - 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. - - - `class ComputerScreenshotContent` - - 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` - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `role: :unknown | :user | :assistant | 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `status: :in_progress | :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. Always set to `message`. - - - `:message` - - - `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 ResponseFunctionToolCallItem` - - 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` - - The unique ID of the function tool call. - - - `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 ResponseFunctionToolCallOutputItem` - - - `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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the function call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseFileSearchToolCall` - - 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` - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `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` - - - `class ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ResponseComputerToolCallOutputItem` - - - `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: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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}]` - - 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. - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchCall` - - - `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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchOutputItem` - - - `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[Tool]` - - The loaded tool definitions returned by tool search. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The type of the item. Always `tool_search_output`. - - - `:tool_search_output` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItem` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ResponseFunctionShellToolCall` - - 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: ResponseLocalEnvironment | ResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class ResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class ResponseContainerReference` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseFunctionShellToolCallOutput` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseApplyPatchToolCall` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseApplyPatchToolCallOutput` - - 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` - - - `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 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` - - - `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` - - - `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` - - - `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` - - - `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 ResponseCustomToolCall` - - 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. - - - `namespace: String` - - The namespace of the custom tool being called. - - - `class ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - -### Conversation Item List - -- `class ConversationItemList` - - A list of Conversation items. - - - `data: Array[ConversationItem]` - - A list of conversation items. - - - `class Message` - - A message to or from the model. - - - `id: String` - - The unique ID of the message. - - - `content: Array[ResponseInputText | ResponseOutputText | TextContent | 6 more]` - - The content of the message - - - `class ResponseInputText` - - 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` - - - `class ResponseOutputText` - - 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 TextContent` - - A text content. - - - `text: String` - - - `type: :text` - - - `:text` - - - `class SummaryTextContent` - - 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 ResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `class ResponseInputImage` - - 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. - - - `class ComputerScreenshotContent` - - 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` - - - `class ResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` - - - `:high` - - - `file_data: 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. - - - `role: :unknown | :user | :assistant | 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `status: :in_progress | :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. Always set to `message`. - - - `:message` - - - `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 ResponseFunctionToolCallItem` - - 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` - - The unique ID of the function tool call. - - - `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 ResponseFunctionToolCallOutputItem` - - - `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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the function call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseFileSearchToolCall` - - 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` - - - `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 ResponseFunctionWebSearch` - - 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{ query, type, queries, 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. - - - `query: String` - - [DEPRECATED] The search query. - - - `type: :search` - - The action type. - - - `:search` - - - `queries: Array[String]` - - The search queries. - - - `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` - - - `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` - - - `class ResponseComputerToolCall` - - 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: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more` - - 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: ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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` - - - `class ResponseComputerToolCallOutputItem` - - - `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: ResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `type: :computer_screenshot` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `:computer_screenshot` - - - `file_id: 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}]` - - 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. - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchCall` - - - `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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseToolSearchOutputItem` - - - `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[Tool]` - - The loaded tool definitions returned by tool search. - - - `class FunctionTool` - - Defines a 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 to enforce strict parameter validation. Default `true`. - - - `type: :function` - - The type of the function tool. Always `function`. - - - `:function` - - - `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. - - - `class FileSearchTool` - - A tool 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 | CompoundFilter` - - 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 | 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. - - - `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 ComputerTool` - - 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 ComputerUsePreviewTool` - - 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 WebSearchTool` - - 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_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` or `connector_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` or `connector_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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `type: :disabled` - - Disable outbound network access. Always `disabled`. - - - `:disabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `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[ContainerNetworkPolicyDomainSecret]` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: String` - - The domain associated with the secret. - - - `name: String` - - The name of the secret to inject for the domain. - - - `value: String` - - The secret value to inject for the domain. - - - `type: :code_interpreter` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `:code_interpreter` - - - `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 FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `type: :shell` - - The type of the shell tool. Always `shell`. - - - `:shell` - - - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - - - `class ContainerAuto` - - - `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: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `class ContainerNetworkPolicyDisabled` - - - `class ContainerNetworkPolicyAllowlist` - - - `skills: Array[SkillReference | InlineSkill]` - - An optional list of skills referenced by id or inline data. - - - `class SkillReference` - - - `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 InlineSkill` - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: String` - - Base64-encoded skill zip bundle. - - - `media_type: :"application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `:"application/zip"` - - - `type: :base64` - - The type of the inline skill source. Must be `base64`. - - - `:base64` - - - `type: :inline` - - Defines an inline skill for this request. - - - `:inline` - - - `class LocalEnvironment` - - - `type: :local` - - Use a local computer environment. - - - `:local` - - - `skills: Array[LocalSkill]` - - An optional list of skills. - - - `description: String` - - The description of the skill. - - - `name: String` - - The name of the skill. - - - `path: String` - - The path to the directory containing the skill. - - - `class ContainerReference` - - - `container_id: String` - - The ID of the referenced container. - - - `type: :container_reference` - - References a container created with the /v1/containers endpoint - - - `:container_reference` - - - `class CustomTool` - - A 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` - - - `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_: CustomToolInputFormat` - - 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 NamespaceTool` - - 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, defer_loading, 3 more} | CustomTool]` - - The function/custom tools available inside this namespace. - - - `class Function` - - - `name: String` - - - `type: :function` - - - `:function` - - - `defer_loading: bool` - - Whether this function should be deferred and discovered via tool search. - - - `description: String` - - - `parameters: untyped` - - - `strict: bool` - - - `class CustomTool` - - A 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 ToolSearchTool` - - 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 WebSearchPreviewTool` - - This tool searches the web 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 ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :apply_patch` - - The type of the tool. Always `apply_patch`. - - - `:apply_patch` - - - `type: :tool_search_output` - - The type of the item. Always `tool_search_output`. - - - `:tool_search_output` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseReasoningItem` - - 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` - - - `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 ResponseCompactionItem` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseCodeInterpreterToolCall` - - 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` - - - `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` - - - `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` - - - `status: :in_progress | :completed | :incomplete` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `class ResponseFunctionShellToolCall` - - 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: ResponseLocalEnvironment | ResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class ResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class ResponseContainerReference` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseFunctionShellToolCallOutput` - - 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` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class ResponseApplyPatchToolCall` - - 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` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class ResponseApplyPatchToolCallOutput` - - 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` - - - `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 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` - - - `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` - - - `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` - - - `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` - - - `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 ResponseCustomToolCall` - - 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. - - - `namespace: String` - - The namespace of the custom tool being called. - - - `class ResponseCustomToolCallOutput` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - 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[ResponseInputText | ResponseInputImage | ResponseInputFile]` - - Text, image, or file output of the custom tool call. - - - `class ResponseInputText` - - A text input to the model. - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ResponseInputFile` - - 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. - - - `first_id: String` - - The ID of the first item in the list. - - - `has_more: bool` - - Whether there are more items available. - - - `last_id: String` - - The ID of the last item in the list. - - - `object: :list` - - The type of object returned, must be `list`. - - - `:list`