ruby/resources/conversations/methods/create/index.md

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.
        
        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 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 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 for more information.
  - id: String
    
    The unique ID of the web search tool call.
  - action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}
    
    An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).
    - class Search
      
      Action type "search" - Performs a web search query.
      - type: :search
        
        The action type.
        
        :search
      - queries: Array[String]
        
        The search queries.
      - query: String
        
        The search query.
      - sources: Array[Source{ type, url}]
        
        The sources used in the search.
        
        type: :url
        
        The type of source. Always url.
        
        :url
        
        url: String
        
        The URL of the source.
    - class OpenPage
      
      Action type "open_page" - Opens a specific URL from search results.
      - type: :open_page
        
        The action type.
        
        :open_page
      - url: String
        
        The URL opened by the model.
    - class FindInPage
      
      Action type "find_in_page": Searches for a pattern within a loaded page.
      - pattern: String
        
        The pattern or text to search for within the page.
      - type: :find_in_page
        
        The action type.
        
        :find_in_page
      - url: String
        
        The URL of the page searched for the pattern.
  - status: :in_progress | :searching | :completed | :failed
    
    The status of the web search tool call.
    - :in_progress
    - :searching
    - :completed
    - :failed
  - type: :web_search_call
    
    The type of the web search tool call. Always web_search_call.
    - :web_search_call
- class ResponseFunctionToolCall
  
  A tool call to run a function. See the function calling guide 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
        
        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.
      - 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.
      - 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.
      - 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.
      - 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.
      - 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 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 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.
      - 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, it will match this filter.
        
        tool_names: Array[String]
        
        List of allowed tool names.
      - authorization: String
        
        An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.
      - connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more
        
        Identifier for service connectors, like those available in ChatGPT. One of server_url, connector_id, or tunnel_id must be provided. Learn more about service connectors here.
        
        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, 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, it will match this filter.
        
        tool_names: Array[String]
        
        List of allowed tool names.
        
        McpToolApprovalSetting = :always | :never
        
        Specify a single approval policy for all tools. One of always or never. When set to always, all tools will require approval. When set to never, all tools will not require approval.
        
        :always
        
        :never
      - server_description: String
        
        Optional description of the MCP server, used to provide more context.
      - server_url: String
        
        The URL for the MCP server. One of server_url, connector_id, or tunnel_id must be provided.
      - tunnel_id: String
        
        The Secure MCP Tunnel ID to use instead of a direct server URL. One of server_url, connector_id, or tunnel_id must be provided.
    - class CodeInterpreter
      
      A tool that runs Python code to help generate a response to a prompt.
      - container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}
        
        The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional memory_limit setting.
        
        String = String
        
        The container ID.
        
        class CodeInterpreterToolAuto
        
        Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
        
        type: :auto
        
        Always auto.
        
        :auto
        
        file_ids: Array[String]
        
        An optional list of uploaded files to make available to your code.
        
        memory_limit: :"1g" | :"4g" | :"16g" | :"64g"
        
        The memory limit for the code interpreter container.
        
        :"1g"
        
        :"4g"
        
        :"16g"
        
        :"64g"
        
        network_policy: 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
      - 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
      - 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.
      - 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 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 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 AdditionalTools
  - role: :developer
    
    The role that provided the additional tools. Only developer is supported.
    - :developer
  - tools: Array[Tool]
    
    A list of additional tools made available at this item.
    - class FunctionTool
      
      Defines a function in your own code the model can choose to call. Learn more about function calling.
    - class FileSearchTool
      
      A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
    - class ComputerTool
      
      A tool that controls a virtual computer. Learn more about the computer tool.
    - class ComputerUsePreviewTool
      
      A tool that controls a virtual computer. Learn more about the computer tool.
    - class WebSearchTool
      
      Search the Internet for sources related to the prompt. Learn more about the web search tool.
    - class Mcp
      
      Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
    - class CodeInterpreter
      
      A tool that runs Python code to help generate a response to a prompt.
    - class ImageGeneration
      
      A tool that generates images using the GPT image models.
    - class LocalShell
      
      A tool that allows the model to execute shell commands in a local environment.
    - class FunctionShellTool
      
      A tool that allows the model to execute shell commands.
    - class CustomTool
      
      A custom tool that processes input using a specified format. Learn more about custom tools
    - class NamespaceTool
      
      Groups function/custom tools under a shared namespace.
    - class ToolSearchTool
      
      Hosted or BYOT tool search configuration for deferred tools.
    - class WebSearchPreviewTool
      
      This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
    - class ApplyPatchTool
      
      Allows the assistant to create, delete, or update files using unified diffs.
  - type: :additional_tools
    
    The item type. Always additional_tools.
    - :additional_tools
  - id: String
    
    The unique ID of this additional tools item.
- 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.
  - 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.
  - 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.
      - 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

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

conversation = openai.conversations.create

puts(conversation)

Response

{
  "id": "id",
  "created_at": 0,
  "metadata": {},
  "object": "conversation"
}

ruby/resources/conversations/methods/create/index.md 2026-06-16 21:57 UTC to 2026-06-17 18:02 UTC

Create a conversation

Parameters

Returns

Example

Response

ruby/resources/conversations/methods/create/index.md +9 −4