Conversations

Create a conversation

Conversation conversations().create(ConversationCreateParamsparams = ConversationCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

post /conversations

Create a conversation.

Parameters

• ConversationCreateParams params

  • Optional<List<ResponseInputItem>> items

    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 content

        Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.

        • String

        • List<ResponseInputContent>

          • class ResponseInputText:

            A text input to the model.

            • String text

              The text input to the model.

            • JsonValue; type "input_text"constant

              The type of the input item. Always input_text.

              • INPUT_TEXT("input_text")

          • class ResponseInputImage:

            An image input to the model. Learn about image inputs.

            • Detail detail

              The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

              • LOW("low")

              • HIGH("high")

              • AUTO("auto")

              • ORIGINAL("original")

            • JsonValue; type "input_image"constant

              The type of the input item. Always input_image.

              • INPUT_IMAGE("input_image")

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> imageUrl

              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.

            • JsonValue; type "input_file"constant

              The type of the input item. Always input_file.

              • INPUT_FILE("input_file")

            • Optional<Detail> detail

              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("low")

              • HIGH("high")

            • Optional<String> fileData

              The content of the file to be sent to the model.

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> fileUrl

              The URL of the file to be sent to the model.

            • Optional<String> filename

              The name of the file to be sent to the model.

      • Role role

        The role of the message input. One of user, assistant, system, or developer.

        • USER("user")

        • ASSISTANT("assistant")

        • SYSTEM("system")

        • DEVELOPER("developer")

      • Optional<Phase> phase

        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("commentary")

        • FINAL_ANSWER("final_answer")

      • Optional<Type> type

        The type of the message input. Always message.

        • MESSAGE("message")

    • Message

      • List<ResponseInputContent> content

        A list of one or many input items to the model, containing different content types.

        • 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.

      • Role role

        The role of the message input. One of user, system, or developer.

        • USER("user")

        • SYSTEM("system")

        • DEVELOPER("developer")

      • Optional<Status> status

        The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • Optional<Type> type

        The type of the message input. Always set to message.

        • MESSAGE("message")

    • class ResponseOutputMessage:

      An output message from the model.

      • String id

        The unique ID of the output message.

      • List<Content> content

        The content of the output message.

        • class ResponseOutputText:

          A text output from the model.

          • List<Annotation> annotations

            The annotations of the text output.

            • class FileCitation:

              A citation to a file.

              • String fileId

                The ID of the file.

              • String filename

                The filename of the file cited.

              • long index

                The index of the file in the list of files.

              • JsonValue; type "file_citation"constant

                The type of the file citation. Always file_citation.

                • FILE_CITATION("file_citation")

            • class UrlCitation:

              A citation for a web resource used to generate a model response.

              • long endIndex

                The index of the last character of the URL citation in the message.

              • long startIndex

                The index of the first character of the URL citation in the message.

              • String title

                The title of the web resource.

              • JsonValue; type "url_citation"constant

                The type of the URL citation. Always url_citation.

                • URL_CITATION("url_citation")

              • String url

                The URL of the web resource.

            • class ContainerFileCitation:

              A citation for a container file used to generate a model response.

              • String containerId

                The ID of the container file.

              • long endIndex

                The index of the last character of the container file citation in the message.

              • String fileId

                The ID of the file.

              • String filename

                The filename of the container file cited.

              • long startIndex

                The index of the first character of the container file citation in the message.

              • JsonValue; type "container_file_citation"constant

                The type of the container file citation. Always container_file_citation.

                • CONTAINER_FILE_CITATION("container_file_citation")

            • class FilePath:

              A path to a file.

              • String fileId

                The ID of the file.

              • long index

                The index of the file in the list of files.

              • JsonValue; type "file_path"constant

                The type of the file path. Always file_path.

                • FILE_PATH("file_path")

          • String text

            The text output from the model.

          • JsonValue; type "output_text"constant

            The type of the output text. Always output_text.

            • OUTPUT_TEXT("output_text")

          • Optional<List<Logprob>> logprobs

            • String token

            • List<long> bytes

            • double logprob

            • List<TopLogprob> topLogprobs

              • String token

              • List<long> bytes

              • double logprob

        • class ResponseOutputRefusal:

          A refusal from the model.

          • String refusal

            The refusal explanation from the model.

          • JsonValue; type "refusal"constant

            The type of the refusal. Always refusal.

            • REFUSAL("refusal")

      • JsonValue; role "assistant"constant

        The role of the output message. Always assistant.

        • ASSISTANT("assistant")

      • Status status

        The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • JsonValue; type "message"constant

        The type of the output message. Always message.

        • MESSAGE("message")

      • Optional<Phase> phase

        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("commentary")

        • FINAL_ANSWER("final_answer")

    • class ResponseFileSearchToolCall:

      The results of a file search tool call. See the file search guide for more information.

      • String id

        The unique ID of the file search tool call.

      • List<String> queries

        The queries used to search for files.

      • Status status

        The status of the file search tool call. One of in_progress, searching, incomplete or failed,

        • IN_PROGRESS("in_progress")

        • SEARCHING("searching")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

        • FAILED("failed")

      • JsonValue; type "file_search_call"constant

        The type of the file search tool call. Always file_search_call.

        • FILE_SEARCH_CALL("file_search_call")

      • Optional<List<Result>> results

        The results of the file search tool call.

        • Optional<Attributes> attributes

          Set of 16 key-value pairs that can be attached to an object. 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

          • double

          • boolean

        • Optional<String> fileId

          The unique ID of the file.

        • Optional<String> filename

          The name of the file.

        • Optional<Double> score

          The relevance score of the file - a value between 0 and 1.

        • Optional<String> text

          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.

      • String id

        The unique ID of the computer call.

      • String callId

        An identifier used when responding to the tool call with output.

      • List<PendingSafetyCheck> pendingSafetyChecks

        The pending safety checks for the computer call.

        • String id

          The ID of the pending safety check.

        • Optional<String> code

          The type of the pending safety check.

        • Optional<String> message

          Details about the pending safety check.

      • Status status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • Type type

        The type of the computer call. Always computer_call.

        • COMPUTER_CALL("computer_call")

      • Optional<Action> action

        A click action.

        • class Click:

          A click action.

          • Button button

            Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.

            • LEFT("left")

            • RIGHT("right")

            • WHEEL("wheel")

            • BACK("back")

            • FORWARD("forward")

          • JsonValue; type "click"constant

            Specifies the event type. For a click action, this property is always click.

            • CLICK("click")

          • long x

            The x-coordinate where the click occurred.

          • long y

            The y-coordinate where the click occurred.

          • Optional<List<String>> keys

            The keys being held while clicking.

        • class DoubleClick:

          A double click action.

          • Optional<List<String>> keys

            The keys being held while double-clicking.

          • JsonValue; type "double_click"constant

            Specifies the event type. For a double click action, this property is always set to double_click.

            • DOUBLE_CLICK("double_click")

          • long x

            The x-coordinate where the double click occurred.

          • long y

            The y-coordinate where the double click occurred.

        • class Drag:

          A drag action.

          • List<Path> path

            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 }
            ]
            

            • long x

              The x-coordinate.

            • long y

              The y-coordinate.

          • JsonValue; type "drag"constant

            Specifies the event type. For a drag action, this property is always set to drag.

            • DRAG("drag")

          • Optional<List<String>> keys

            The keys being held while dragging the mouse.

        • class Keypress:

          A collection of keypresses the model would like to perform.

          • List<String> keys

            The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

          • JsonValue; type "keypress"constant

            Specifies the event type. For a keypress action, this property is always set to keypress.

            • KEYPRESS("keypress")

        • class Move:

          A mouse move action.

          • JsonValue; type "move"constant

            Specifies the event type. For a move action, this property is always set to move.

            • MOVE("move")

          • long x

            The x-coordinate to move to.

          • long y

            The y-coordinate to move to.

          • Optional<List<String>> keys

            The keys being held while moving the mouse.

        • JsonValue;

          • JsonValue; type "screenshot"constant

            Specifies the event type. For a screenshot action, this property is always set to screenshot.

            • SCREENSHOT("screenshot")

        • class Scroll:

          A scroll action.

          • long scrollX

            The horizontal scroll distance.

          • long scrollY

            The vertical scroll distance.

          • JsonValue; type "scroll"constant

            Specifies the event type. For a scroll action, this property is always set to scroll.

            • SCROLL("scroll")

          • long x

            The x-coordinate where the scroll occurred.

          • long y

            The y-coordinate where the scroll occurred.

          • Optional<List<String>> keys

            The keys being held while scrolling.

        • class Type:

          An action to type in text.

          • String text

            The text to type.

          • JsonValue; type "type"constant

            Specifies the event type. For a type action, this property is always set to type.

            • TYPE("type")

        • JsonValue;

          • JsonValue; type "wait"constant

            Specifies the event type. For a wait action, this property is always set to wait.

            • WAIT("wait")

      • Optional<List<ComputerAction>> actions

        Flattened batched actions for computer_use. Each action includes an type discriminator and action-specific fields.

        • Click

          • Button button

            Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.

            • LEFT("left")

            • RIGHT("right")

            • WHEEL("wheel")

            • BACK("back")

            • FORWARD("forward")

          • JsonValue; type "click"constant

            Specifies the event type. For a click action, this property is always click.

            • CLICK("click")

          • long x

            The x-coordinate where the click occurred.

          • long y

            The y-coordinate where the click occurred.

          • Optional<List<String>> keys

            The keys being held while clicking.

        • DoubleClick

          • Optional<List<String>> keys

            The keys being held while double-clicking.

          • JsonValue; type "double_click"constant

            Specifies the event type. For a double click action, this property is always set to double_click.

            • DOUBLE_CLICK("double_click")

          • long x

            The x-coordinate where the double click occurred.

          • long y

            The y-coordinate where the double click occurred.

        • Drag

          • List<Path> path

            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 }
            ]
            

            • long x

              The x-coordinate.

            • long y

              The y-coordinate.

          • JsonValue; type "drag"constant

            Specifies the event type. For a drag action, this property is always set to drag.

            • DRAG("drag")

          • Optional<List<String>> keys

            The keys being held while dragging the mouse.

        • Keypress

          • List<String> keys

            The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

          • JsonValue; type "keypress"constant

            Specifies the event type. For a keypress action, this property is always set to keypress.

            • KEYPRESS("keypress")

        • Move

          • JsonValue; type "move"constant

            Specifies the event type. For a move action, this property is always set to move.

            • MOVE("move")

          • long x

            The x-coordinate to move to.

          • long y

            The y-coordinate to move to.

          • Optional<List<String>> keys

            The keys being held while moving the mouse.

        • JsonValue;

          • JsonValue; type "screenshot"constant

            Specifies the event type. For a screenshot action, this property is always set to screenshot.

            • SCREENSHOT("screenshot")

        • Scroll

          • long scrollX

            The horizontal scroll distance.

          • long scrollY

            The vertical scroll distance.

          • JsonValue; type "scroll"constant

            Specifies the event type. For a scroll action, this property is always set to scroll.

            • SCROLL("scroll")

          • long x

            The x-coordinate where the scroll occurred.

          • long y

            The y-coordinate where the scroll occurred.

          • Optional<List<String>> keys

            The keys being held while scrolling.

        • Type

          • String text

            The text to type.

          • JsonValue; type "type"constant

            Specifies the event type. For a type action, this property is always set to type.

            • TYPE("type")

        • JsonValue;

          • JsonValue; type "wait"constant

            Specifies the event type. For a wait action, this property is always set to wait.

            • WAIT("wait")

    • ComputerCallOutput

      • String callId

        The ID of the computer tool call that produced the output.

      • ResponseComputerToolCallOutputScreenshot output

        A computer screenshot image used with the computer use tool.

        • JsonValue; type "computer_screenshot"constant

          Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

          • COMPUTER_SCREENSHOT("computer_screenshot")

        • Optional<String> fileId

          The identifier of an uploaded file that contains the screenshot.

        • Optional<String> imageUrl

          The URL of the screenshot image.

      • JsonValue; type "computer_call_output"constant

        The type of the computer tool call output. Always computer_call_output.

        • COMPUTER_CALL_OUTPUT("computer_call_output")

      • Optional<String> id

        The ID of the computer tool call output.

      • Optional<List<AcknowledgedSafetyCheck>> acknowledgedSafetyChecks

        The safety checks reported by the API that have been acknowledged by the developer.

        • String id

          The ID of the pending safety check.

        • Optional<String> code

          The type of the pending safety check.

        • Optional<String> message

          Details about the pending safety check.

      • Optional<Status> status

        The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • class ResponseFunctionWebSearch:

      The results of a web search tool call. See the web search guide for more information.

      • String id

        The unique ID of the web search tool call.

      • Action action

        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.

          • String query

            [DEPRECATED] The search query.

          • JsonValue; type "search"constant

            The action type.

            • SEARCH("search")

          • Optional<List<String>> queries

            The search queries.

          • Optional<List<Source>> sources

            The sources used in the search.

            • JsonValue; type "url"constant

              The type of source. Always url.

              • URL("url")

            • String url

              The URL of the source.

        • class OpenPage:

          Action type "open_page" - Opens a specific URL from search results.

          • JsonValue; type "open_page"constant

            The action type.

            • OPEN_PAGE("open_page")

          • Optional<String> url

            The URL opened by the model.

        • class FindInPage:

          Action type "find_in_page": Searches for a pattern within a loaded page.

          • String pattern

            The pattern or text to search for within the page.

          • JsonValue; type "find_in_page"constant

            The action type.

            • FIND_IN_PAGE("find_in_page")

          • String url

            The URL of the page searched for the pattern.

      • Status status

        The status of the web search tool call.

        • IN_PROGRESS("in_progress")

        • SEARCHING("searching")

        • COMPLETED("completed")

        • FAILED("failed")

      • JsonValue; type "web_search_call"constant

        The type of the web search tool call. Always web_search_call.

        • WEB_SEARCH_CALL("web_search_call")

    • class ResponseFunctionToolCall:

      A tool call to run a function. See the function calling guide for more information.

      • String arguments

        A JSON string of the arguments to pass to the function.

      • String callId

        The unique ID of the function tool call generated by the model.

      • String name

        The name of the function to run.

      • JsonValue; type "function_call"constant

        The type of the function tool call. Always function_call.

        • FUNCTION_CALL("function_call")

      • Optional<String> id

        The unique ID of the function tool call.

      • Optional<String> namespace

        The namespace of the function to run.

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • FunctionCallOutput

      • String callId

        The unique ID of the function tool call generated by the model.

      • Output output

        Text, image, or file output of the function tool call.

        • String

        • List<ResponseFunctionCallOutputItem>

          • class ResponseInputTextContent:

            A text input to the model.

            • String text

              The text input to the model.

            • JsonValue; type "input_text"constant

              The type of the input item. Always input_text.

              • INPUT_TEXT("input_text")

          • class ResponseInputImageContent:

            An image input to the model. Learn about image inputs

            • JsonValue; type "input_image"constant

              The type of the input item. Always input_image.

              • INPUT_IMAGE("input_image")

            • Optional<Detail> detail

              The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

              • LOW("low")

              • HIGH("high")

              • AUTO("auto")

              • ORIGINAL("original")

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> imageUrl

              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.

            • JsonValue; type "input_file"constant

              The type of the input item. Always input_file.

              • INPUT_FILE("input_file")

            • Optional<Detail> detail

              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("low")

              • HIGH("high")

            • Optional<String> fileData

              The base64-encoded data of the file to be sent to the model.

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> fileUrl

              The URL of the file to be sent to the model.

            • Optional<String> filename

              The name of the file to be sent to the model.

      • JsonValue; type "function_call_output"constant

        The type of the function tool call output. Always function_call_output.

        • FUNCTION_CALL_OUTPUT("function_call_output")

      • Optional<String> id

        The unique ID of the function tool call output. Populated when this item is returned via API.

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ToolSearchCall

      • JsonValue arguments

        The arguments supplied to the tool search call.

      • JsonValue; type "tool_search_call"constant

        The item type. Always tool_search_call.

        • TOOL_SEARCH_CALL("tool_search_call")

      • Optional<String> id

        The unique ID of this tool search call.

      • Optional<String> callId

        The unique ID of the tool search call generated by the model.

      • Optional<Execution> execution

        Whether tool search was executed by the server or by the client.

        • SERVER("server")

        • CLIENT("client")

      • Optional<Status> status

        The status of the tool search call.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • class ResponseToolSearchOutputItemParam:

      • List<Tool> tools

        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.

          • String name

            The name of the function to call.

          • Optional<Parameters> parameters

            A JSON schema object describing the parameters of the function.

          • Optional<Boolean> strict

            Whether to enforce strict parameter validation. Default true.

          • JsonValue; type "function"constant

            The type of the function tool. Always function.

            • FUNCTION("function")

          • Optional<Boolean> deferLoading

            Whether this function is deferred and loaded via tool search.

          • Optional<String> description

            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.

          • JsonValue; type "file_search"constant

            The type of the file search tool. Always file_search.

            • FILE_SEARCH("file_search")

          • List<String> vectorStoreIds

            The IDs of the vector stores to search.

          • Optional<Filters> filters

            A filter to apply.

            • class ComparisonFilter:

              A filter used to compare a specified attribute key to a given value using a defined comparison operation.

              • String key

                The key to compare against the value.

              • Type type

                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("eq")

                • NE("ne")

                • GT("gt")

                • GTE("gte")

                • LT("lt")

                • LTE("lte")

                • IN("in")

                • NIN("nin")

              • Value value

                The value to compare against the attribute key; supports string, number, or boolean types.

                • String

                • double

                • boolean

                • List<ComparisonFilterValueItem>

                  • String

                  • double

            • class CompoundFilter:

              Combine multiple filters using and or or.

              • List<Filter> filters

                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.

                • JsonValue

              • Type type

                Type of operation: and or or.

                • AND("and")

                • OR("or")

          • Optional<Long> maxNumResults

            The maximum number of results to return. This number should be between 1 and 50 inclusive.

          • Optional<RankingOptions> rankingOptions

            Ranking options for search.

            • Optional<HybridSearch> hybridSearch

              Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

              • double embeddingWeight

                The weight of the embedding in the reciprocal ranking fusion.

              • double textWeight

                The weight of the text in the reciprocal ranking fusion.

            • Optional<Ranker> ranker

              The ranker to use for the file search.

              • AUTO("auto")

              • DEFAULT_2024_11_15("default-2024-11-15")

            • Optional<Double> scoreThreshold

              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.

          • JsonValue; type "computer"constant

            The type of the computer tool. Always computer.

            • COMPUTER("computer")

        • class ComputerUsePreviewTool:

          A tool that controls a virtual computer. Learn more about the computer tool.

          • long displayHeight

            The height of the computer display.

          • long displayWidth

            The width of the computer display.

          • Environment environment

            The type of computer environment to control.

            • WINDOWS("windows")

            • MAC("mac")

            • LINUX("linux")

            • UBUNTU("ubuntu")

            • BROWSER("browser")

          • JsonValue; type "computer_use_preview"constant

            The type of the computer use tool. Always computer_use_preview.

            • 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 type

            The type of the web search tool. One of web_search or web_search_2025_08_26.

            • WEB_SEARCH("web_search")

            • WEB_SEARCH_2025_08_26("web_search_2025_08_26")

          • Optional<Filters> filters

            Filters for the search.

            • Optional<List<String>> allowedDomains

              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"]

          • Optional<SearchContextSize> searchContextSize

            High 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("low")

            • MEDIUM("medium")

            • HIGH("high")

          • Optional<UserLocation> userLocation

            The approximate location of the user.

            • Optional<String> city

              Free text input for the city of the user, e.g. San Francisco.

            • Optional<String> country

              The two-letter ISO country code of the user, e.g. US.

            • Optional<String> region

              Free text input for the region of the user, e.g. California.

            • Optional<String> timezone

              The IANA timezone of the user, e.g. America/Los_Angeles.

            • Optional<Type> type

              The type of location approximation. Always approximate.

              • APPROXIMATE("approximate")

        • Mcp

          • String serverLabel

            A label for this MCP server, used to identify it in tool calls.

          • JsonValue; type "mcp"constant

            The type of the MCP tool. Always mcp.

            • MCP("mcp")

          • Optional<AllowedTools> allowedTools

            List of allowed tool names or a filter object.

            • List<String>

            • class McpToolFilter:

              A filter object to specify which tools are allowed.

              • Optional<Boolean> readOnly

                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.

              • Optional<List<String>> toolNames

                List of allowed tool names.

          • Optional<String> authorization

            An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.

          • Optional<ConnectorId> connectorId

            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.

            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_dropbox")

            • CONNECTOR_GMAIL("connector_gmail")

            • CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")

            • CONNECTOR_GOOGLEDRIVE("connector_googledrive")

            • CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")

            • CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")

            • CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")

            • CONNECTOR_SHAREPOINT("connector_sharepoint")

          • Optional<Boolean> deferLoading

            Whether this MCP tool is deferred and discovered via tool search.

          • Optional<Headers> headers

            Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.

          • Optional<RequireApproval> requireApproval

            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.

              • Optional<Always> always

                A filter object to specify which tools are allowed.

                • Optional<Boolean> readOnly

                  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.

                • Optional<List<String>> toolNames

                  List of allowed tool names.

              • Optional<Never> never

                A filter object to specify which tools are allowed.

                • Optional<Boolean> readOnly

                  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.

                • Optional<List<String>> toolNames

                  List of allowed tool names.

            • enum McpToolApprovalSetting:

              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("always")

              • NEVER("never")

          • Optional<String> serverDescription

            Optional description of the MCP server, used to provide more context.

          • Optional<String> serverUrl

            The URL for the MCP server. One of server_url or connector_id must be provided.

        • CodeInterpreter

          • Container container

            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

            • class CodeInterpreterToolAuto:

              Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

              • JsonValue; type "auto"constant

                Always auto.

                • AUTO("auto")

              • Optional<List<String>> fileIds

                An optional list of uploaded files to make available to your code.

              • Optional<MemoryLimit> memoryLimit

                The memory limit for the code interpreter container.

                • _1G("1g")

                • _4G("4g")

                • _16G("16g")

                • _64G("64g")

              • Optional<NetworkPolicy> networkPolicy

                Network access policy for the container.

                • class ContainerNetworkPolicyDisabled:

                  • JsonValue; type "disabled"constant

                    Disable outbound network access. Always disabled.

                    • DISABLED("disabled")

                • class ContainerNetworkPolicyAllowlist:

                  • List<String> allowedDomains

                    A list of allowed domains when type is allowlist.

                  • JsonValue; type "allowlist"constant

                    Allow outbound network access only to specified domains. Always allowlist.

                    • ALLOWLIST("allowlist")

                  • Optional<List<ContainerNetworkPolicyDomainSecret>> domainSecrets

                    Optional domain-scoped secrets for allowlisted domains.

                    • String domain

                      The domain associated with the secret.

                    • String name

                      The name of the secret to inject for the domain.

                    • String value

                      The secret value to inject for the domain.

          • JsonValue; type "code_interpreter"constant

            The type of the code interpreter tool. Always code_interpreter.

            • CODE_INTERPRETER("code_interpreter")

        • ImageGeneration

          • JsonValue; type "image_generation"constant

            The type of the image generation tool. Always image_generation.

            • IMAGE_GENERATION("image_generation")

          • Optional<Action> action

            Whether to generate a new image or edit an existing image. Default: auto.

            • GENERATE("generate")

            • EDIT("edit")

            • AUTO("auto")

          • Optional<Background> background

            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("transparent")

            • OPAQUE("opaque")

            • AUTO("auto")

          • Optional<InputFidelity> inputFidelity

            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("high")

            • LOW("low")

          • Optional<InputImageMask> inputImageMask

            Optional mask for inpainting. Contains image_url (string, optional) and file_id (string, optional).

            • Optional<String> fileId

              File ID for the mask image.

            • Optional<String> imageUrl

              Base64-encoded mask image.

          • Optional<Model> model

            The image generation model to use. Default: gpt-image-1.

            • GPT_IMAGE_1("gpt-image-1")

            • GPT_IMAGE_1_MINI("gpt-image-1-mini")

            • GPT_IMAGE_2("gpt-image-2")

            • GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")

            • GPT_IMAGE_1_5("gpt-image-1.5")

            • CHATGPT_IMAGE_LATEST("chatgpt-image-latest")

          • Optional<Moderation> moderation

            Moderation level for the generated image. Default: auto.

            • AUTO("auto")

            • LOW("low")

          • Optional<Long> outputCompression

            Compression level for the output image. Default: 100.

          • Optional<OutputFormat> outputFormat

            The output format of the generated image. One of png, webp, or jpeg. Default: png.

            • PNG("png")

            • WEBP("webp")

            • JPEG("jpeg")

          • Optional<Long> partialImages

            Number of partial images to generate in streaming mode, from 0 (default value) to 3.

          • Optional<Quality> quality

            The quality of the generated image. One of low, medium, high, or auto. Default: auto.

            • LOW("low")

            • MEDIUM("medium")

            • HIGH("high")

            • AUTO("auto")

          • Optional<String> size

            The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.

        • JsonValue;

          • JsonValue; type "local_shell"constant

            The type of the local shell tool. Always local_shell.

            • LOCAL_SHELL("local_shell")

        • class FunctionShellTool:

          A tool that allows the model to execute shell commands.

          • JsonValue; type "shell"constant

            The type of the shell tool. Always shell.

            • SHELL("shell")

          • Optional<Environment> environment

            • class ContainerAuto:

              • JsonValue; type "container_auto"constant

                Automatically creates a container for this request

                • CONTAINER_AUTO("container_auto")

              • Optional<List<String>> fileIds

                An optional list of uploaded files to make available to your code.

              • Optional<MemoryLimit> memoryLimit

                The memory limit for the container.

                • _1G("1g")

                • _4G("4g")

                • _16G("16g")

                • _64G("64g")

              • Optional<NetworkPolicy> networkPolicy

                Network access policy for the container.

                • class ContainerNetworkPolicyDisabled:

                • class ContainerNetworkPolicyAllowlist:

              • Optional<List<Skill>> skills

                An optional list of skills referenced by id or inline data.

                • class SkillReference:

                  • String skillId

                    The ID of the referenced skill.

                  • JsonValue; type "skill_reference"constant

                    References a skill created with the /v1/skills endpoint.

                    • SKILL_REFERENCE("skill_reference")

                  • Optional<String> version

                    Optional skill version. Use a positive integer or 'latest'. Omit for default.

                • class InlineSkill:

                  • String description

                    The description of the skill.

                  • String name

                    The name of the skill.

                  • InlineSkillSource source

                    Inline skill payload

                    • String data

                      Base64-encoded skill zip bundle.

                    • JsonValue; mediaType "application/zip"constant

                      The media type of the inline skill payload. Must be application/zip.

                      • APPLICATION_ZIP("application/zip")

                    • JsonValue; type "base64"constant

                      The type of the inline skill source. Must be base64.

                      • BASE64("base64")

                  • JsonValue; type "inline"constant

                    Defines an inline skill for this request.

                    • INLINE("inline")

            • class LocalEnvironment:

              • JsonValue; type "local"constant

                Use a local computer environment.

                • LOCAL("local")

              • Optional<List<LocalSkill>> skills

                An optional list of skills.

                • String description

                  The description of the skill.

                • String name

                  The name of the skill.

                • String path

                  The path to the directory containing the skill.

            • class ContainerReference:

              • String containerId

                The ID of the referenced container.

              • JsonValue; type "container_reference"constant

                References a container created with the /v1/containers endpoint

                • CONTAINER_REFERENCE("container_reference")

        • class CustomTool:

          A custom tool that processes input using a specified format. Learn more about custom tools

          • String name

            The name of the custom tool, used to identify it in tool calls.

          • JsonValue; type "custom"constant

            The type of the custom tool. Always custom.

            • CUSTOM("custom")

          • Optional<Boolean> deferLoading

            Whether this tool should be deferred and discovered via tool search.

          • Optional<String> description

            Optional description of the custom tool, used to provide more context.

          • Optional<CustomToolInputFormat> format

            The input format for the custom tool. Default is unconstrained text.

            • JsonValue;

              • JsonValue; type "text"constant

                Unconstrained text format. Always text.

                • TEXT("text")

            • Grammar

              • String definition

                The grammar definition.

              • Syntax syntax

                The syntax of the grammar definition. One of lark or regex.

                • LARK("lark")

                • REGEX("regex")

              • JsonValue; type "grammar"constant

                Grammar format. Always grammar.

                • GRAMMAR("grammar")

        • class NamespaceTool:

          Groups function/custom tools under a shared namespace.

          • String description

            A description of the namespace shown to the model.

          • String name

            The namespace name used in tool calls (for example, crm).

          • List<Tool> tools

            The function/custom tools available inside this namespace.

            • class Function:

              • String name

              • JsonValue; type "function"constant

                • FUNCTION("function")

              • Optional<Boolean> deferLoading

                Whether this function should be deferred and discovered via tool search.

              • Optional<String> description

              • Optional<JsonValue> parameters

              • Optional<Boolean> strict

            • class CustomTool:

              A custom tool that processes input using a specified format. Learn more about custom tools

          • JsonValue; type "namespace"constant

            The type of the tool. Always namespace.

            • NAMESPACE("namespace")

        • class ToolSearchTool:

          Hosted or BYOT tool search configuration for deferred tools.

          • JsonValue; type "tool_search"constant

            The type of the tool. Always tool_search.

            • TOOL_SEARCH("tool_search")

          • Optional<String> description

            Description shown to the model for a client-executed tool search tool.

          • Optional<Execution> execution

            Whether tool search is executed by the server or by the client.

            • SERVER("server")

            • CLIENT("client")

          • Optional<JsonValue> parameters

            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 type

            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")

            • WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")

          • Optional<List<SearchContentType>> searchContentTypes

            • TEXT("text")

            • IMAGE("image")

          • Optional<SearchContextSize> searchContextSize

            High 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("low")

            • MEDIUM("medium")

            • HIGH("high")

          • Optional<UserLocation> userLocation

            The user's location.

            • JsonValue; type "approximate"constant

              The type of location approximation. Always approximate.

              • APPROXIMATE("approximate")

            • Optional<String> city

              Free text input for the city of the user, e.g. San Francisco.

            • Optional<String> country

              The two-letter ISO country code of the user, e.g. US.

            • Optional<String> region

              Free text input for the region of the user, e.g. California.

            • Optional<String> timezone

              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.

          • JsonValue; type "apply_patch"constant

            The type of the tool. Always apply_patch.

            • APPLY_PATCH("apply_patch")

      • JsonValue; type "tool_search_output"constant

        The item type. Always tool_search_output.

        • TOOL_SEARCH_OUTPUT("tool_search_output")

      • Optional<String> id

        The unique ID of this tool search output.

      • Optional<String> callId

        The unique ID of the tool search call generated by the model.

      • Optional<Execution> execution

        Whether tool search was executed by the server or by the client.

        • SERVER("server")

        • CLIENT("client")

      • Optional<Status> status

        The status of the tool search output.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("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.

      • String id

        The unique identifier of the reasoning content.

      • List<Summary> summary

        Reasoning summary content.

        • String text

          A summary of the reasoning output from the model so far.

        • JsonValue; type "summary_text"constant

          The type of the object. Always summary_text.

          • SUMMARY_TEXT("summary_text")

      • JsonValue; type "reasoning"constant

        The type of the object. Always reasoning.

        • REASONING("reasoning")

      • Optional<List<Content>> content

        Reasoning text content.

        • String text

          The reasoning text from the model.

        • JsonValue; type "reasoning_text"constant

          The type of the reasoning text. Always reasoning_text.

          • REASONING_TEXT("reasoning_text")

      • Optional<String> encryptedContent

        The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter.

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • class ResponseCompactionItemParam:

      A compaction item generated by the v1/responses/compact API.

      • String encryptedContent

        The encrypted content of the compaction summary.

      • JsonValue; type "compaction"constant

        The type of the item. Always compaction.

        • COMPACTION("compaction")

      • Optional<String> id

        The ID of the compaction item.

    • ImageGenerationCall

      • String id

        The unique ID of the image generation call.

      • Optional<String> result

        The generated image encoded in base64.

      • Status status

        The status of the image generation call.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • GENERATING("generating")

        • FAILED("failed")

      • JsonValue; type "image_generation_call"constant

        The type of the image generation call. Always image_generation_call.

        • IMAGE_GENERATION_CALL("image_generation_call")

    • class ResponseCodeInterpreterToolCall:

      A tool call to run code.

      • String id

        The unique ID of the code interpreter tool call.

      • Optional<String> code

        The code to run, or null if not available.

      • String containerId

        The ID of the container used to run the code.

      • Optional<List<Output>> outputs

        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.

          • String logs

            The logs output from the code interpreter.

          • JsonValue; type "logs"constant

            The type of the output. Always logs.

            • LOGS("logs")

        • class Image:

          The image output from the code interpreter.

          • JsonValue; type "image"constant

            The type of the output. Always image.

            • IMAGE("image")

          • String url

            The URL of the image output from the code interpreter.

      • Status status

        The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

        • INTERPRETING("interpreting")

        • FAILED("failed")

      • JsonValue; type "code_interpreter_call"constant

        The type of the code interpreter tool call. Always code_interpreter_call.

        • CODE_INTERPRETER_CALL("code_interpreter_call")

    • LocalShellCall

      • String id

        The unique ID of the local shell call.

      • Action action

        Execute a shell command on the server.

        • List<String> command

          The command to run.

        • Env env

          Environment variables to set for the command.

        • JsonValue; type "exec"constant

          The type of the local shell action. Always exec.

          • EXEC("exec")

        • Optional<Long> timeoutMs

          Optional timeout in milliseconds for the command.

        • Optional<String> user

          Optional user to run the command as.

        • Optional<String> workingDirectory

          Optional working directory to run the command in.

      • String callId

        The unique ID of the local shell tool call generated by the model.

      • Status status

        The status of the local shell call.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • JsonValue; type "local_shell_call"constant

        The type of the local shell call. Always local_shell_call.

        • LOCAL_SHELL_CALL("local_shell_call")

    • LocalShellCallOutput

      • String id

        The unique ID of the local shell tool call generated by the model.

      • String output

        A JSON string of the output of the local shell tool call.

      • JsonValue; type "local_shell_call_output"constant

        The type of the local shell tool call output. Always local_shell_call_output.

        • LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ShellCall

      • Action action

        The shell commands and limits that describe how to run the tool call.

        • List<String> commands

          Ordered shell commands for the execution environment to run.

        • Optional<Long> maxOutputLength

          Maximum number of UTF-8 characters to capture from combined stdout and stderr output.

        • Optional<Long> timeoutMs

          Maximum wall-clock time in milliseconds to allow the shell commands to run.

      • String callId

        The unique ID of the shell tool call generated by the model.

      • JsonValue; type "shell_call"constant

        The type of the item. Always shell_call.

        • SHELL_CALL("shell_call")

      • Optional<String> id

        The unique ID of the shell tool call. Populated when this item is returned via API.

      • Optional<Environment> environment

        The environment to execute the shell commands in.

        • class LocalEnvironment:

        • class ContainerReference:

      • Optional<Status> status

        The status of the shell call. One of in_progress, completed, or incomplete.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ShellCallOutput

      • String callId

        The unique ID of the shell tool call generated by the model.

      • List<ResponseFunctionShellCallOutputContent> output

        Captured chunks of stdout and stderr output, along with their associated outcomes.

        • Outcome outcome

          The exit or timeout outcome associated with this shell call.

          • JsonValue;

            • JsonValue; type "timeout"constant

              The outcome type. Always timeout.

              • TIMEOUT("timeout")

          • class Exit:

            Indicates that the shell commands finished and returned an exit code.

            • long exitCode

              The exit code returned by the shell process.

            • JsonValue; type "exit"constant

              The outcome type. Always exit.

              • EXIT("exit")

        • String stderr

          Captured stderr output for the shell call.

        • String stdout

          Captured stdout output for the shell call.

      • JsonValue; type "shell_call_output"constant

        The type of the item. Always shell_call_output.

        • SHELL_CALL_OUTPUT("shell_call_output")

      • Optional<String> id

        The unique ID of the shell tool call output. Populated when this item is returned via API.

      • Optional<Long> maxOutputLength

        The maximum number of UTF-8 characters captured for this shell call's combined output.

      • Optional<Status> status

        The status of the shell call output.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ApplyPatchCall

      • String callId

        The unique ID of the apply patch tool call generated by the model.

      • Operation operation

        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.

          • String diff

            Unified diff content to apply when creating the file.

          • String path

            Path of the file to create relative to the workspace root.

          • JsonValue; type "create_file"constant

            The operation type. Always create_file.

            • CREATE_FILE("create_file")

        • class DeleteFile:

          Instruction for deleting an existing file via the apply_patch tool.

          • String path

            Path of the file to delete relative to the workspace root.

          • JsonValue; type "delete_file"constant

            The operation type. Always delete_file.

            • DELETE_FILE("delete_file")

        • class UpdateFile:

          Instruction for updating an existing file via the apply_patch tool.

          • String diff

            Unified diff content to apply to the existing file.

          • String path

            Path of the file to update relative to the workspace root.

          • JsonValue; type "update_file"constant

            The operation type. Always update_file.

            • UPDATE_FILE("update_file")

      • Status status

        The status of the apply patch tool call. One of in_progress or completed.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

      • JsonValue; type "apply_patch_call"constant

        The type of the item. Always apply_patch_call.

        • APPLY_PATCH_CALL("apply_patch_call")

      • Optional<String> id

        The unique ID of the apply patch tool call. Populated when this item is returned via API.

    • ApplyPatchCallOutput

      • String callId

        The unique ID of the apply patch tool call generated by the model.

      • Status status

        The status of the apply patch tool call output. One of completed or failed.

        • COMPLETED("completed")

        • FAILED("failed")

      • JsonValue; type "apply_patch_call_output"constant

        The type of the item. Always apply_patch_call_output.

        • APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")

      • Optional<String> id

        The unique ID of the apply patch tool call output. Populated when this item is returned via API.

      • Optional<String> output

        Optional human-readable log text from the apply patch tool (e.g., patch results or errors).

    • McpListTools

      • String id

        The unique ID of the list.

      • String serverLabel

        The label of the MCP server.

      • List<Tool> tools

        The tools available on the server.

        • JsonValue inputSchema

          The JSON schema describing the tool's input.

        • String name

          The name of the tool.

        • Optional<JsonValue> annotations

          Additional annotations about the tool.

        • Optional<String> description

          The description of the tool.

      • JsonValue; type "mcp_list_tools"constant

        The type of the item. Always mcp_list_tools.

        • MCP_LIST_TOOLS("mcp_list_tools")

      • Optional<String> error

        Error message if the server could not list tools.

    • McpApprovalRequest

      • String id

        The unique ID of the approval request.

      • String arguments

        A JSON string of arguments for the tool.

      • String name

        The name of the tool to run.

      • String serverLabel

        The label of the MCP server making the request.

      • JsonValue; type "mcp_approval_request"constant

        The type of the item. Always mcp_approval_request.

        • MCP_APPROVAL_REQUEST("mcp_approval_request")

    • McpApprovalResponse

      • String approvalRequestId

        The ID of the approval request being answered.

      • boolean approve

        Whether the request was approved.

      • JsonValue; type "mcp_approval_response"constant

        The type of the item. Always mcp_approval_response.

        • MCP_APPROVAL_RESPONSE("mcp_approval_response")

      • Optional<String> id

        The unique ID of the approval response

      • Optional<String> reason

        Optional reason for the decision.

    • McpCall

      • String id

        The unique ID of the tool call.

      • String arguments

        A JSON string of the arguments passed to the tool.

      • String name

        The name of the tool that was run.

      • String serverLabel

        The label of the MCP server running the tool.

      • JsonValue; type "mcp_call"constant

        The type of the item. Always mcp_call.

        • MCP_CALL("mcp_call")

      • Optional<String> approvalRequestId

        Unique identifier for the MCP tool call approval request. Include this value in a subsequent mcp_approval_response input to approve or reject the corresponding tool call.

      • Optional<String> error

        The error from the tool call, if any.

      • Optional<String> output

        The output from the tool call.

      • Optional<Status> status

        The status of the tool call. One of in_progress, completed, incomplete, calling, or failed.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

        • CALLING("calling")

        • FAILED("failed")

    • class ResponseCustomToolCallOutput:

      The output of a custom tool call from your code, being sent back to the model.

      • String callId

        The call ID, used to map this custom tool call output to a custom tool call.

      • Output output

        The output from the custom tool call generated by your code. Can be a string or an list of output content.

        • String

        • List<FunctionAndCustomToolCallOutput>

          • 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.

      • JsonValue; type "custom_tool_call_output"constant

        The type of the custom tool call output. Always custom_tool_call_output.

        • CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")

      • Optional<String> id

        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.

      • String callId

        An identifier used to map this custom tool call to a tool call output.

      • String input

        The input for the custom tool call generated by the model.

      • String name

        The name of the custom tool being called.

      • JsonValue; type "custom_tool_call"constant

        The type of the custom tool call. Always custom_tool_call.

        • CUSTOM_TOOL_CALL("custom_tool_call")

      • Optional<String> id

        The unique ID of the custom tool call in the OpenAI platform.

      • Optional<String> namespace

        The namespace of the custom tool being called.

    • ItemReference

      • String id

        The ID of the item to reference.

      • Optional<Type> type

        The type of item to reference. Always item_reference.

        • ITEM_REFERENCE("item_reference")

  • Optional<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:

  • String id

    The unique ID of the conversation.

  • long createdAt

    The time at which the conversation was created, measured in seconds since the Unix epoch.

  • JsonValue 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.

  • JsonValue; object_ "conversation"constant

    The object type, which is always conversation.

    • CONVERSATION("conversation")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.ConversationCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        Conversation conversation = client.conversations().create();
    }
}

Response

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

Retrieve a conversation

Conversation conversations().retrieve(ConversationRetrieveParamsparams = ConversationRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /conversations/{conversation_id}

Get a conversation

Parameters

• ConversationRetrieveParams params

  • Optional<String> conversationId

Returns

• class Conversation:

  • String id

    The unique ID of the conversation.

  • long createdAt

    The time at which the conversation was created, measured in seconds since the Unix epoch.

  • JsonValue 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.

  • JsonValue; object_ "conversation"constant

    The object type, which is always conversation.

    • CONVERSATION("conversation")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.ConversationRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        Conversation conversation = client.conversations().retrieve("conv_123");
    }
}

Response

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

Update a conversation

Conversation conversations().update(ConversationUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

post /conversations/{conversation_id}

Update a conversation

Parameters

• ConversationUpdateParams params

  • Optional<String> conversationId

  • Optional<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:

  • String id

    The unique ID of the conversation.

  • long createdAt

    The time at which the conversation was created, measured in seconds since the Unix epoch.

  • JsonValue 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.

  • JsonValue; object_ "conversation"constant

    The object type, which is always conversation.

    • CONVERSATION("conversation")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.ConversationUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ConversationUpdateParams params = ConversationUpdateParams.builder()
            .conversationId("conv_123")
            .metadata(ConversationUpdateParams.Metadata.builder()
                .putAdditionalProperty("foo", JsonValue.from("string"))
                .build())
            .build();
        Conversation conversation = client.conversations().update(params);
    }
}

Response

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

Delete a conversation

ConversationDeletedResource conversations().delete(ConversationDeleteParamsparams = ConversationDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

delete /conversations/{conversation_id}

Delete a conversation. Items in the conversation will not be deleted.

Parameters

• ConversationDeleteParams params

  • Optional<String> conversationId

Returns

• class ConversationDeletedResource:

  • String id

  • boolean deleted

  • JsonValue; object_ "conversation.deleted"constant

    • CONVERSATION_DELETED("conversation.deleted")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.conversations.ConversationDeleteParams;
import com.openai.models.conversations.ConversationDeletedResource;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ConversationDeletedResource conversationDeletedResource = client.conversations().delete("conv_123");
    }
}

Response

{
  "id": "id",
  "deleted": true,
  "object": "conversation.deleted"
}

Domain Types

Computer Screenshot Content

• class ComputerScreenshotContent:

  A screenshot of a computer.

  • Detail detail

    The detail level of the screenshot image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

    • LOW("low")

    • HIGH("high")

    • AUTO("auto")

    • ORIGINAL("original")

  • Optional<String> fileId

    The identifier of an uploaded file that contains the screenshot.

  • Optional<String> imageUrl

    The URL of the screenshot image.

  • JsonValue; type "computer_screenshot"constant

    Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

    • COMPUTER_SCREENSHOT("computer_screenshot")

Conversation

• class Conversation:

  • String id

    The unique ID of the conversation.

  • long createdAt

    The time at which the conversation was created, measured in seconds since the Unix epoch.

  • JsonValue 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.

  • JsonValue; object_ "conversation"constant

    The object type, which is always conversation.

    • CONVERSATION("conversation")

Conversation Deleted

• class ConversationDeleted:

  • String id

  • boolean deleted

  • JsonValue; object_ "conversation.deleted"constant

    • CONVERSATION_DELETED("conversation.deleted")

Conversation Deleted Resource

• class ConversationDeletedResource:

  • String id

  • boolean deleted

  • JsonValue; object_ "conversation.deleted"constant

    • CONVERSATION_DELETED("conversation.deleted")

Message

• class Message:

  A message to or from the model.

  • String id

    The unique ID of the message.

  • List<Content> content

    The content of the message

    • class ResponseInputText:

      A text input to the model.

      • String text

        The text input to the model.

      • JsonValue; type "input_text"constant

        The type of the input item. Always input_text.

        • INPUT_TEXT("input_text")

    • class ResponseOutputText:

      A text output from the model.

      • List<Annotation> annotations

        The annotations of the text output.

        • class FileCitation:

          A citation to a file.

          • String fileId

            The ID of the file.

          • String filename

            The filename of the file cited.

          • long index

            The index of the file in the list of files.

          • JsonValue; type "file_citation"constant

            The type of the file citation. Always file_citation.

            • FILE_CITATION("file_citation")

        • class UrlCitation:

          A citation for a web resource used to generate a model response.

          • long endIndex

            The index of the last character of the URL citation in the message.

          • long startIndex

            The index of the first character of the URL citation in the message.

          • String title

            The title of the web resource.

          • JsonValue; type "url_citation"constant

            The type of the URL citation. Always url_citation.

            • URL_CITATION("url_citation")

          • String url

            The URL of the web resource.

        • class ContainerFileCitation:

          A citation for a container file used to generate a model response.

          • String containerId

            The ID of the container file.

          • long endIndex

            The index of the last character of the container file citation in the message.

          • String fileId

            The ID of the file.

          • String filename

            The filename of the container file cited.

          • long startIndex

            The index of the first character of the container file citation in the message.

          • JsonValue; type "container_file_citation"constant

            The type of the container file citation. Always container_file_citation.

            • CONTAINER_FILE_CITATION("container_file_citation")

        • class FilePath:

          A path to a file.

          • String fileId

            The ID of the file.

          • long index

            The index of the file in the list of files.

          • JsonValue; type "file_path"constant

            The type of the file path. Always file_path.

            • FILE_PATH("file_path")

      • String text

        The text output from the model.

      • JsonValue; type "output_text"constant

        The type of the output text. Always output_text.

        • OUTPUT_TEXT("output_text")

      • Optional<List<Logprob>> logprobs

        • String token

        • List<long> bytes

        • double logprob

        • List<TopLogprob> topLogprobs

          • String token

          • List<long> bytes

          • double logprob

    • class TextContent:

      A text content.

      • String text

      • JsonValue; type "text"constant

        • TEXT("text")

    • class SummaryTextContent:

      A summary text from the model.

      • String text

        A summary of the reasoning output from the model so far.

      • JsonValue; type "summary_text"constant

        The type of the object. Always summary_text.

        • SUMMARY_TEXT("summary_text")

    • class ReasoningText:

      Reasoning text from the model.

      • String text

        The reasoning text from the model.

      • JsonValue; type "reasoning_text"constant

        The type of the reasoning text. Always reasoning_text.

        • REASONING_TEXT("reasoning_text")

    • class ResponseOutputRefusal:

      A refusal from the model.

      • String refusal

        The refusal explanation from the model.

      • JsonValue; type "refusal"constant

        The type of the refusal. Always refusal.

        • REFUSAL("refusal")

    • class ResponseInputImage:

      An image input to the model. Learn about image inputs.

      • Detail detail

        The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

        • LOW("low")

        • HIGH("high")

        • AUTO("auto")

        • ORIGINAL("original")

      • JsonValue; type "input_image"constant

        The type of the input item. Always input_image.

        • INPUT_IMAGE("input_image")

      • Optional<String> fileId

        The ID of the file to be sent to the model.

      • Optional<String> imageUrl

        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 detail

        The detail level of the screenshot image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

        • LOW("low")

        • HIGH("high")

        • AUTO("auto")

        • ORIGINAL("original")

      • Optional<String> fileId

        The identifier of an uploaded file that contains the screenshot.

      • Optional<String> imageUrl

        The URL of the screenshot image.

      • JsonValue; type "computer_screenshot"constant

        Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

        • COMPUTER_SCREENSHOT("computer_screenshot")

    • class ResponseInputFile:

      A file input to the model.

      • JsonValue; type "input_file"constant

        The type of the input item. Always input_file.

        • INPUT_FILE("input_file")

      • Optional<Detail> detail

        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("low")

        • HIGH("high")

      • Optional<String> fileData

        The content of the file to be sent to the model.

      • Optional<String> fileId

        The ID of the file to be sent to the model.

      • Optional<String> fileUrl

        The URL of the file to be sent to the model.

      • Optional<String> filename

        The name of the file to be sent to the model.

  • Role role

    The role of the message. One of unknown, user, assistant, system, critic, discriminator, developer, or tool.

    • UNKNOWN("unknown")

    • USER("user")

    • ASSISTANT("assistant")

    • SYSTEM("system")

    • CRITIC("critic")

    • DISCRIMINATOR("discriminator")

    • DEVELOPER("developer")

    • TOOL("tool")

  • Status status

    The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

    • IN_PROGRESS("in_progress")

    • COMPLETED("completed")

    • INCOMPLETE("incomplete")

  • JsonValue; type "message"constant

    The type of the message. Always set to message.

    • MESSAGE("message")

  • Optional<Phase> phase

    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("commentary")

    • FINAL_ANSWER("final_answer")

Summary Text Content

• class SummaryTextContent:

  A summary text from the model.

  • String text

    A summary of the reasoning output from the model so far.

  • JsonValue; type "summary_text"constant

    The type of the object. Always summary_text.

    • SUMMARY_TEXT("summary_text")

Text Content

• class TextContent:

  A text content.

  • String text

  • JsonValue; type "text"constant

    • TEXT("text")

Items

Create items

ConversationItemList conversations().items().create(ItemCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

post /conversations/{conversation_id}/items

Create items in a conversation with the given ID.

Parameters

• ItemCreateParams params

  • Optional<String> conversationId

  • Optional<List<ResponseIncludable>> include

    Additional fields to include in the response. See the include parameter for listing Conversation items above for more information.

    • FILE_SEARCH_CALL_RESULTS("file_search_call.results")

    • WEB_SEARCH_CALL_RESULTS("web_search_call.results")

    • WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")

    • MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")

    • COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")

    • CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")

    • REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")

    • MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")

  • List<ResponseInputItem> items

    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 content

        Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.

        • String

        • List<ResponseInputContent>

          • class ResponseInputText:

            A text input to the model.

            • String text

              The text input to the model.

            • JsonValue; type "input_text"constant

              The type of the input item. Always input_text.

              • INPUT_TEXT("input_text")

          • class ResponseInputImage:

            An image input to the model. Learn about image inputs.

            • Detail detail

              The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

              • LOW("low")

              • HIGH("high")

              • AUTO("auto")

              • ORIGINAL("original")

            • JsonValue; type "input_image"constant

              The type of the input item. Always input_image.

              • INPUT_IMAGE("input_image")

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> imageUrl

              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.

            • JsonValue; type "input_file"constant

              The type of the input item. Always input_file.

              • INPUT_FILE("input_file")

            • Optional<Detail> detail

              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("low")

              • HIGH("high")

            • Optional<String> fileData

              The content of the file to be sent to the model.

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> fileUrl

              The URL of the file to be sent to the model.

            • Optional<String> filename

              The name of the file to be sent to the model.

      • Role role

        The role of the message input. One of user, assistant, system, or developer.

        • USER("user")

        • ASSISTANT("assistant")

        • SYSTEM("system")

        • DEVELOPER("developer")

      • Optional<Phase> phase

        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("commentary")

        • FINAL_ANSWER("final_answer")

      • Optional<Type> type

        The type of the message input. Always message.

        • MESSAGE("message")

    • Message

      • List<ResponseInputContent> content

        A list of one or many input items to the model, containing different content types.

        • 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.

      • Role role

        The role of the message input. One of user, system, or developer.

        • USER("user")

        • SYSTEM("system")

        • DEVELOPER("developer")

      • Optional<Status> status

        The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • Optional<Type> type

        The type of the message input. Always set to message.

        • MESSAGE("message")

    • class ResponseOutputMessage:

      An output message from the model.

      • String id

        The unique ID of the output message.

      • List<Content> content

        The content of the output message.

        • class ResponseOutputText:

          A text output from the model.

          • List<Annotation> annotations

            The annotations of the text output.

            • class FileCitation:

              A citation to a file.

              • String fileId

                The ID of the file.

              • String filename

                The filename of the file cited.

              • long index

                The index of the file in the list of files.

              • JsonValue; type "file_citation"constant

                The type of the file citation. Always file_citation.

                • FILE_CITATION("file_citation")

            • class UrlCitation:

              A citation for a web resource used to generate a model response.

              • long endIndex

                The index of the last character of the URL citation in the message.

              • long startIndex

                The index of the first character of the URL citation in the message.

              • String title

                The title of the web resource.

              • JsonValue; type "url_citation"constant

                The type of the URL citation. Always url_citation.

                • URL_CITATION("url_citation")

              • String url

                The URL of the web resource.

            • class ContainerFileCitation:

              A citation for a container file used to generate a model response.

              • String containerId

                The ID of the container file.

              • long endIndex

                The index of the last character of the container file citation in the message.

              • String fileId

                The ID of the file.

              • String filename

                The filename of the container file cited.

              • long startIndex

                The index of the first character of the container file citation in the message.

              • JsonValue; type "container_file_citation"constant

                The type of the container file citation. Always container_file_citation.

                • CONTAINER_FILE_CITATION("container_file_citation")

            • class FilePath:

              A path to a file.

              • String fileId

                The ID of the file.

              • long index

                The index of the file in the list of files.

              • JsonValue; type "file_path"constant

                The type of the file path. Always file_path.

                • FILE_PATH("file_path")

          • String text

            The text output from the model.

          • JsonValue; type "output_text"constant

            The type of the output text. Always output_text.

            • OUTPUT_TEXT("output_text")

          • Optional<List<Logprob>> logprobs

            • String token

            • List<long> bytes

            • double logprob

            • List<TopLogprob> topLogprobs

              • String token

              • List<long> bytes

              • double logprob

        • class ResponseOutputRefusal:

          A refusal from the model.

          • String refusal

            The refusal explanation from the model.

          • JsonValue; type "refusal"constant

            The type of the refusal. Always refusal.

            • REFUSAL("refusal")

      • JsonValue; role "assistant"constant

        The role of the output message. Always assistant.

        • ASSISTANT("assistant")

      • Status status

        The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • JsonValue; type "message"constant

        The type of the output message. Always message.

        • MESSAGE("message")

      • Optional<Phase> phase

        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("commentary")

        • FINAL_ANSWER("final_answer")

    • class ResponseFileSearchToolCall:

      The results of a file search tool call. See the file search guide for more information.

      • String id

        The unique ID of the file search tool call.

      • List<String> queries

        The queries used to search for files.

      • Status status

        The status of the file search tool call. One of in_progress, searching, incomplete or failed,

        • IN_PROGRESS("in_progress")

        • SEARCHING("searching")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

        • FAILED("failed")

      • JsonValue; type "file_search_call"constant

        The type of the file search tool call. Always file_search_call.

        • FILE_SEARCH_CALL("file_search_call")

      • Optional<List<Result>> results

        The results of the file search tool call.

        • Optional<Attributes> attributes

          Set of 16 key-value pairs that can be attached to an object. 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

          • double

          • boolean

        • Optional<String> fileId

          The unique ID of the file.

        • Optional<String> filename

          The name of the file.

        • Optional<Double> score

          The relevance score of the file - a value between 0 and 1.

        • Optional<String> text

          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.

      • String id

        The unique ID of the computer call.

      • String callId

        An identifier used when responding to the tool call with output.

      • List<PendingSafetyCheck> pendingSafetyChecks

        The pending safety checks for the computer call.

        • String id

          The ID of the pending safety check.

        • Optional<String> code

          The type of the pending safety check.

        • Optional<String> message

          Details about the pending safety check.

      • Status status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • Type type

        The type of the computer call. Always computer_call.

        • COMPUTER_CALL("computer_call")

      • Optional<Action> action

        A click action.

        • class Click:

          A click action.

          • Button button

            Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.

            • LEFT("left")

            • RIGHT("right")

            • WHEEL("wheel")

            • BACK("back")

            • FORWARD("forward")

          • JsonValue; type "click"constant

            Specifies the event type. For a click action, this property is always click.

            • CLICK("click")

          • long x

            The x-coordinate where the click occurred.

          • long y

            The y-coordinate where the click occurred.

          • Optional<List<String>> keys

            The keys being held while clicking.

        • class DoubleClick:

          A double click action.

          • Optional<List<String>> keys

            The keys being held while double-clicking.

          • JsonValue; type "double_click"constant

            Specifies the event type. For a double click action, this property is always set to double_click.

            • DOUBLE_CLICK("double_click")

          • long x

            The x-coordinate where the double click occurred.

          • long y

            The y-coordinate where the double click occurred.

        • class Drag:

          A drag action.

          • List<Path> path

            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 }
            ]
            

            • long x

              The x-coordinate.

            • long y

              The y-coordinate.

          • JsonValue; type "drag"constant

            Specifies the event type. For a drag action, this property is always set to drag.

            • DRAG("drag")

          • Optional<List<String>> keys

            The keys being held while dragging the mouse.

        • class Keypress:

          A collection of keypresses the model would like to perform.

          • List<String> keys

            The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

          • JsonValue; type "keypress"constant

            Specifies the event type. For a keypress action, this property is always set to keypress.

            • KEYPRESS("keypress")

        • class Move:

          A mouse move action.

          • JsonValue; type "move"constant

            Specifies the event type. For a move action, this property is always set to move.

            • MOVE("move")

          • long x

            The x-coordinate to move to.

          • long y

            The y-coordinate to move to.

          • Optional<List<String>> keys

            The keys being held while moving the mouse.

        • JsonValue;

          • JsonValue; type "screenshot"constant

            Specifies the event type. For a screenshot action, this property is always set to screenshot.

            • SCREENSHOT("screenshot")

        • class Scroll:

          A scroll action.

          • long scrollX

            The horizontal scroll distance.

          • long scrollY

            The vertical scroll distance.

          • JsonValue; type "scroll"constant

            Specifies the event type. For a scroll action, this property is always set to scroll.

            • SCROLL("scroll")

          • long x

            The x-coordinate where the scroll occurred.

          • long y

            The y-coordinate where the scroll occurred.

          • Optional<List<String>> keys

            The keys being held while scrolling.

        • class Type:

          An action to type in text.

          • String text

            The text to type.

          • JsonValue; type "type"constant

            Specifies the event type. For a type action, this property is always set to type.

            • TYPE("type")

        • JsonValue;

          • JsonValue; type "wait"constant

            Specifies the event type. For a wait action, this property is always set to wait.

            • WAIT("wait")

      • Optional<List<ComputerAction>> actions

        Flattened batched actions for computer_use. Each action includes an type discriminator and action-specific fields.

        • Click

          • Button button

            Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.

            • LEFT("left")

            • RIGHT("right")

            • WHEEL("wheel")

            • BACK("back")

            • FORWARD("forward")

          • JsonValue; type "click"constant

            Specifies the event type. For a click action, this property is always click.

            • CLICK("click")

          • long x

            The x-coordinate where the click occurred.

          • long y

            The y-coordinate where the click occurred.

          • Optional<List<String>> keys

            The keys being held while clicking.

        • DoubleClick

          • Optional<List<String>> keys

            The keys being held while double-clicking.

          • JsonValue; type "double_click"constant

            Specifies the event type. For a double click action, this property is always set to double_click.

            • DOUBLE_CLICK("double_click")

          • long x

            The x-coordinate where the double click occurred.

          • long y

            The y-coordinate where the double click occurred.

        • Drag

          • List<Path> path

            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 }
            ]
            

            • long x

              The x-coordinate.

            • long y

              The y-coordinate.

          • JsonValue; type "drag"constant

            Specifies the event type. For a drag action, this property is always set to drag.

            • DRAG("drag")

          • Optional<List<String>> keys

            The keys being held while dragging the mouse.

        • Keypress

          • List<String> keys

            The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

          • JsonValue; type "keypress"constant

            Specifies the event type. For a keypress action, this property is always set to keypress.

            • KEYPRESS("keypress")

        • Move

          • JsonValue; type "move"constant

            Specifies the event type. For a move action, this property is always set to move.

            • MOVE("move")

          • long x

            The x-coordinate to move to.

          • long y

            The y-coordinate to move to.

          • Optional<List<String>> keys

            The keys being held while moving the mouse.

        • JsonValue;

          • JsonValue; type "screenshot"constant

            Specifies the event type. For a screenshot action, this property is always set to screenshot.

            • SCREENSHOT("screenshot")

        • Scroll

          • long scrollX

            The horizontal scroll distance.

          • long scrollY

            The vertical scroll distance.

          • JsonValue; type "scroll"constant

            Specifies the event type. For a scroll action, this property is always set to scroll.

            • SCROLL("scroll")

          • long x

            The x-coordinate where the scroll occurred.

          • long y

            The y-coordinate where the scroll occurred.

          • Optional<List<String>> keys

            The keys being held while scrolling.

        • Type

          • String text

            The text to type.

          • JsonValue; type "type"constant

            Specifies the event type. For a type action, this property is always set to type.

            • TYPE("type")

        • JsonValue;

          • JsonValue; type "wait"constant

            Specifies the event type. For a wait action, this property is always set to wait.

            • WAIT("wait")

    • ComputerCallOutput

      • String callId

        The ID of the computer tool call that produced the output.

      • ResponseComputerToolCallOutputScreenshot output

        A computer screenshot image used with the computer use tool.

        • JsonValue; type "computer_screenshot"constant

          Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

          • COMPUTER_SCREENSHOT("computer_screenshot")

        • Optional<String> fileId

          The identifier of an uploaded file that contains the screenshot.

        • Optional<String> imageUrl

          The URL of the screenshot image.

      • JsonValue; type "computer_call_output"constant

        The type of the computer tool call output. Always computer_call_output.

        • COMPUTER_CALL_OUTPUT("computer_call_output")

      • Optional<String> id

        The ID of the computer tool call output.

      • Optional<List<AcknowledgedSafetyCheck>> acknowledgedSafetyChecks

        The safety checks reported by the API that have been acknowledged by the developer.

        • String id

          The ID of the pending safety check.

        • Optional<String> code

          The type of the pending safety check.

        • Optional<String> message

          Details about the pending safety check.

      • Optional<Status> status

        The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • class ResponseFunctionWebSearch:

      The results of a web search tool call. See the web search guide for more information.

      • String id

        The unique ID of the web search tool call.

      • Action action

        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.

          • String query

            [DEPRECATED] The search query.

          • JsonValue; type "search"constant

            The action type.

            • SEARCH("search")

          • Optional<List<String>> queries

            The search queries.

          • Optional<List<Source>> sources

            The sources used in the search.

            • JsonValue; type "url"constant

              The type of source. Always url.

              • URL("url")

            • String url

              The URL of the source.

        • class OpenPage:

          Action type "open_page" - Opens a specific URL from search results.

          • JsonValue; type "open_page"constant

            The action type.

            • OPEN_PAGE("open_page")

          • Optional<String> url

            The URL opened by the model.

        • class FindInPage:

          Action type "find_in_page": Searches for a pattern within a loaded page.

          • String pattern

            The pattern or text to search for within the page.

          • JsonValue; type "find_in_page"constant

            The action type.

            • FIND_IN_PAGE("find_in_page")

          • String url

            The URL of the page searched for the pattern.

      • Status status

        The status of the web search tool call.

        • IN_PROGRESS("in_progress")

        • SEARCHING("searching")

        • COMPLETED("completed")

        • FAILED("failed")

      • JsonValue; type "web_search_call"constant

        The type of the web search tool call. Always web_search_call.

        • WEB_SEARCH_CALL("web_search_call")

    • class ResponseFunctionToolCall:

      A tool call to run a function. See the function calling guide for more information.

      • String arguments

        A JSON string of the arguments to pass to the function.

      • String callId

        The unique ID of the function tool call generated by the model.

      • String name

        The name of the function to run.

      • JsonValue; type "function_call"constant

        The type of the function tool call. Always function_call.

        • FUNCTION_CALL("function_call")

      • Optional<String> id

        The unique ID of the function tool call.

      • Optional<String> namespace

        The namespace of the function to run.

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • FunctionCallOutput

      • String callId

        The unique ID of the function tool call generated by the model.

      • Output output

        Text, image, or file output of the function tool call.

        • String

        • List<ResponseFunctionCallOutputItem>

          • class ResponseInputTextContent:

            A text input to the model.

            • String text

              The text input to the model.

            • JsonValue; type "input_text"constant

              The type of the input item. Always input_text.

              • INPUT_TEXT("input_text")

          • class ResponseInputImageContent:

            An image input to the model. Learn about image inputs

            • JsonValue; type "input_image"constant

              The type of the input item. Always input_image.

              • INPUT_IMAGE("input_image")

            • Optional<Detail> detail

              The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

              • LOW("low")

              • HIGH("high")

              • AUTO("auto")

              • ORIGINAL("original")

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> imageUrl

              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.

            • JsonValue; type "input_file"constant

              The type of the input item. Always input_file.

              • INPUT_FILE("input_file")

            • Optional<Detail> detail

              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("low")

              • HIGH("high")

            • Optional<String> fileData

              The base64-encoded data of the file to be sent to the model.

            • Optional<String> fileId

              The ID of the file to be sent to the model.

            • Optional<String> fileUrl

              The URL of the file to be sent to the model.

            • Optional<String> filename

              The name of the file to be sent to the model.

      • JsonValue; type "function_call_output"constant

        The type of the function tool call output. Always function_call_output.

        • FUNCTION_CALL_OUTPUT("function_call_output")

      • Optional<String> id

        The unique ID of the function tool call output. Populated when this item is returned via API.

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ToolSearchCall

      • JsonValue arguments

        The arguments supplied to the tool search call.

      • JsonValue; type "tool_search_call"constant

        The item type. Always tool_search_call.

        • TOOL_SEARCH_CALL("tool_search_call")

      • Optional<String> id

        The unique ID of this tool search call.

      • Optional<String> callId

        The unique ID of the tool search call generated by the model.

      • Optional<Execution> execution

        Whether tool search was executed by the server or by the client.

        • SERVER("server")

        • CLIENT("client")

      • Optional<Status> status

        The status of the tool search call.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • class ResponseToolSearchOutputItemParam:

      • List<Tool> tools

        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.

          • String name

            The name of the function to call.

          • Optional<Parameters> parameters

            A JSON schema object describing the parameters of the function.

          • Optional<Boolean> strict

            Whether to enforce strict parameter validation. Default true.

          • JsonValue; type "function"constant

            The type of the function tool. Always function.

            • FUNCTION("function")

          • Optional<Boolean> deferLoading

            Whether this function is deferred and loaded via tool search.

          • Optional<String> description

            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.

          • JsonValue; type "file_search"constant

            The type of the file search tool. Always file_search.

            • FILE_SEARCH("file_search")

          • List<String> vectorStoreIds

            The IDs of the vector stores to search.

          • Optional<Filters> filters

            A filter to apply.

            • class ComparisonFilter:

              A filter used to compare a specified attribute key to a given value using a defined comparison operation.

              • String key

                The key to compare against the value.

              • Type type

                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("eq")

                • NE("ne")

                • GT("gt")

                • GTE("gte")

                • LT("lt")

                • LTE("lte")

                • IN("in")

                • NIN("nin")

              • Value value

                The value to compare against the attribute key; supports string, number, or boolean types.

                • String

                • double

                • boolean

                • List<ComparisonFilterValueItem>

                  • String

                  • double

            • class CompoundFilter:

              Combine multiple filters using and or or.

              • List<Filter> filters

                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.

                • JsonValue

              • Type type

                Type of operation: and or or.

                • AND("and")

                • OR("or")

          • Optional<Long> maxNumResults

            The maximum number of results to return. This number should be between 1 and 50 inclusive.

          • Optional<RankingOptions> rankingOptions

            Ranking options for search.

            • Optional<HybridSearch> hybridSearch

              Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

              • double embeddingWeight

                The weight of the embedding in the reciprocal ranking fusion.

              • double textWeight

                The weight of the text in the reciprocal ranking fusion.

            • Optional<Ranker> ranker

              The ranker to use for the file search.

              • AUTO("auto")

              • DEFAULT_2024_11_15("default-2024-11-15")

            • Optional<Double> scoreThreshold

              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.

          • JsonValue; type "computer"constant

            The type of the computer tool. Always computer.

            • COMPUTER("computer")

        • class ComputerUsePreviewTool:

          A tool that controls a virtual computer. Learn more about the computer tool.

          • long displayHeight

            The height of the computer display.

          • long displayWidth

            The width of the computer display.

          • Environment environment

            The type of computer environment to control.

            • WINDOWS("windows")

            • MAC("mac")

            • LINUX("linux")

            • UBUNTU("ubuntu")

            • BROWSER("browser")

          • JsonValue; type "computer_use_preview"constant

            The type of the computer use tool. Always computer_use_preview.

            • 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 type

            The type of the web search tool. One of web_search or web_search_2025_08_26.

            • WEB_SEARCH("web_search")

            • WEB_SEARCH_2025_08_26("web_search_2025_08_26")

          • Optional<Filters> filters

            Filters for the search.

            • Optional<List<String>> allowedDomains

              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"]

          • Optional<SearchContextSize> searchContextSize

            High 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("low")

            • MEDIUM("medium")

            • HIGH("high")

          • Optional<UserLocation> userLocation

            The approximate location of the user.

            • Optional<String> city

              Free text input for the city of the user, e.g. San Francisco.

            • Optional<String> country

              The two-letter ISO country code of the user, e.g. US.

            • Optional<String> region

              Free text input for the region of the user, e.g. California.

            • Optional<String> timezone

              The IANA timezone of the user, e.g. America/Los_Angeles.

            • Optional<Type> type

              The type of location approximation. Always approximate.

              • APPROXIMATE("approximate")

        • Mcp

          • String serverLabel

            A label for this MCP server, used to identify it in tool calls.

          • JsonValue; type "mcp"constant

            The type of the MCP tool. Always mcp.

            • MCP("mcp")

          • Optional<AllowedTools> allowedTools

            List of allowed tool names or a filter object.

            • List<String>

            • class McpToolFilter:

              A filter object to specify which tools are allowed.

              • Optional<Boolean> readOnly

                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.

              • Optional<List<String>> toolNames

                List of allowed tool names.

          • Optional<String> authorization

            An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.

          • Optional<ConnectorId> connectorId

            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.

            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_dropbox")

            • CONNECTOR_GMAIL("connector_gmail")

            • CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")

            • CONNECTOR_GOOGLEDRIVE("connector_googledrive")

            • CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")

            • CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")

            • CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")

            • CONNECTOR_SHAREPOINT("connector_sharepoint")

          • Optional<Boolean> deferLoading

            Whether this MCP tool is deferred and discovered via tool search.

          • Optional<Headers> headers

            Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.

          • Optional<RequireApproval> requireApproval

            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.

              • Optional<Always> always

                A filter object to specify which tools are allowed.

                • Optional<Boolean> readOnly

                  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.

                • Optional<List<String>> toolNames

                  List of allowed tool names.

              • Optional<Never> never

                A filter object to specify which tools are allowed.

                • Optional<Boolean> readOnly

                  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.

                • Optional<List<String>> toolNames

                  List of allowed tool names.

            • enum McpToolApprovalSetting:

              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("always")

              • NEVER("never")

          • Optional<String> serverDescription

            Optional description of the MCP server, used to provide more context.

          • Optional<String> serverUrl

            The URL for the MCP server. One of server_url or connector_id must be provided.

        • CodeInterpreter

          • Container container

            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

            • class CodeInterpreterToolAuto:

              Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

              • JsonValue; type "auto"constant

                Always auto.

                • AUTO("auto")

              • Optional<List<String>> fileIds

                An optional list of uploaded files to make available to your code.

              • Optional<MemoryLimit> memoryLimit

                The memory limit for the code interpreter container.

                • _1G("1g")

                • _4G("4g")

                • _16G("16g")

                • _64G("64g")

              • Optional<NetworkPolicy> networkPolicy

                Network access policy for the container.

                • class ContainerNetworkPolicyDisabled:

                  • JsonValue; type "disabled"constant

                    Disable outbound network access. Always disabled.

                    • DISABLED("disabled")

                • class ContainerNetworkPolicyAllowlist:

                  • List<String> allowedDomains

                    A list of allowed domains when type is allowlist.

                  • JsonValue; type "allowlist"constant

                    Allow outbound network access only to specified domains. Always allowlist.

                    • ALLOWLIST("allowlist")

                  • Optional<List<ContainerNetworkPolicyDomainSecret>> domainSecrets

                    Optional domain-scoped secrets for allowlisted domains.

                    • String domain

                      The domain associated with the secret.

                    • String name

                      The name of the secret to inject for the domain.

                    • String value

                      The secret value to inject for the domain.

          • JsonValue; type "code_interpreter"constant

            The type of the code interpreter tool. Always code_interpreter.

            • CODE_INTERPRETER("code_interpreter")

        • ImageGeneration

          • JsonValue; type "image_generation"constant

            The type of the image generation tool. Always image_generation.

            • IMAGE_GENERATION("image_generation")

          • Optional<Action> action

            Whether to generate a new image or edit an existing image. Default: auto.

            • GENERATE("generate")

            • EDIT("edit")

            • AUTO("auto")

          • Optional<Background> background

            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("transparent")

            • OPAQUE("opaque")

            • AUTO("auto")

          • Optional<InputFidelity> inputFidelity

            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("high")

            • LOW("low")

          • Optional<InputImageMask> inputImageMask

            Optional mask for inpainting. Contains image_url (string, optional) and file_id (string, optional).

            • Optional<String> fileId

              File ID for the mask image.

            • Optional<String> imageUrl

              Base64-encoded mask image.

          • Optional<Model> model

            The image generation model to use. Default: gpt-image-1.

            • GPT_IMAGE_1("gpt-image-1")

            • GPT_IMAGE_1_MINI("gpt-image-1-mini")

            • GPT_IMAGE_2("gpt-image-2")

            • GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")

            • GPT_IMAGE_1_5("gpt-image-1.5")

            • CHATGPT_IMAGE_LATEST("chatgpt-image-latest")

          • Optional<Moderation> moderation

            Moderation level for the generated image. Default: auto.

            • AUTO("auto")

            • LOW("low")

          • Optional<Long> outputCompression

            Compression level for the output image. Default: 100.

          • Optional<OutputFormat> outputFormat

            The output format of the generated image. One of png, webp, or jpeg. Default: png.

            • PNG("png")

            • WEBP("webp")

            • JPEG("jpeg")

          • Optional<Long> partialImages

            Number of partial images to generate in streaming mode, from 0 (default value) to 3.

          • Optional<Quality> quality

            The quality of the generated image. One of low, medium, high, or auto. Default: auto.

            • LOW("low")

            • MEDIUM("medium")

            • HIGH("high")

            • AUTO("auto")

          • Optional<String> size

            The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.

        • JsonValue;

          • JsonValue; type "local_shell"constant

            The type of the local shell tool. Always local_shell.

            • LOCAL_SHELL("local_shell")

        • class FunctionShellTool:

          A tool that allows the model to execute shell commands.

          • JsonValue; type "shell"constant

            The type of the shell tool. Always shell.

            • SHELL("shell")

          • Optional<Environment> environment

            • class ContainerAuto:

              • JsonValue; type "container_auto"constant

                Automatically creates a container for this request

                • CONTAINER_AUTO("container_auto")

              • Optional<List<String>> fileIds

                An optional list of uploaded files to make available to your code.

              • Optional<MemoryLimit> memoryLimit

                The memory limit for the container.

                • _1G("1g")

                • _4G("4g")

                • _16G("16g")

                • _64G("64g")

              • Optional<NetworkPolicy> networkPolicy

                Network access policy for the container.

                • class ContainerNetworkPolicyDisabled:

                • class ContainerNetworkPolicyAllowlist:

              • Optional<List<Skill>> skills

                An optional list of skills referenced by id or inline data.

                • class SkillReference:

                  • String skillId

                    The ID of the referenced skill.

                  • JsonValue; type "skill_reference"constant

                    References a skill created with the /v1/skills endpoint.

                    • SKILL_REFERENCE("skill_reference")

                  • Optional<String> version

                    Optional skill version. Use a positive integer or 'latest'. Omit for default.

                • class InlineSkill:

                  • String description

                    The description of the skill.

                  • String name

                    The name of the skill.

                  • InlineSkillSource source

                    Inline skill payload

                    • String data

                      Base64-encoded skill zip bundle.

                    • JsonValue; mediaType "application/zip"constant

                      The media type of the inline skill payload. Must be application/zip.

                      • APPLICATION_ZIP("application/zip")

                    • JsonValue; type "base64"constant

                      The type of the inline skill source. Must be base64.

                      • BASE64("base64")

                  • JsonValue; type "inline"constant

                    Defines an inline skill for this request.

                    • INLINE("inline")

            • class LocalEnvironment:

              • JsonValue; type "local"constant

                Use a local computer environment.

                • LOCAL("local")

              • Optional<List<LocalSkill>> skills

                An optional list of skills.

                • String description

                  The description of the skill.

                • String name

                  The name of the skill.

                • String path

                  The path to the directory containing the skill.

            • class ContainerReference:

              • String containerId

                The ID of the referenced container.

              • JsonValue; type "container_reference"constant

                References a container created with the /v1/containers endpoint

                • CONTAINER_REFERENCE("container_reference")

        • class CustomTool:

          A custom tool that processes input using a specified format. Learn more about custom tools

          • String name

            The name of the custom tool, used to identify it in tool calls.

          • JsonValue; type "custom"constant

            The type of the custom tool. Always custom.

            • CUSTOM("custom")

          • Optional<Boolean> deferLoading

            Whether this tool should be deferred and discovered via tool search.

          • Optional<String> description

            Optional description of the custom tool, used to provide more context.

          • Optional<CustomToolInputFormat> format

            The input format for the custom tool. Default is unconstrained text.

            • JsonValue;

              • JsonValue; type "text"constant

                Unconstrained text format. Always text.

                • TEXT("text")

            • Grammar

              • String definition

                The grammar definition.

              • Syntax syntax

                The syntax of the grammar definition. One of lark or regex.

                • LARK("lark")

                • REGEX("regex")

              • JsonValue; type "grammar"constant

                Grammar format. Always grammar.

                • GRAMMAR("grammar")

        • class NamespaceTool:

          Groups function/custom tools under a shared namespace.

          • String description

            A description of the namespace shown to the model.

          • String name

            The namespace name used in tool calls (for example, crm).

          • List<Tool> tools

            The function/custom tools available inside this namespace.

            • class Function:

              • String name

              • JsonValue; type "function"constant

                • FUNCTION("function")

              • Optional<Boolean> deferLoading

                Whether this function should be deferred and discovered via tool search.

              • Optional<String> description

              • Optional<JsonValue> parameters

              • Optional<Boolean> strict

            • class CustomTool:

              A custom tool that processes input using a specified format. Learn more about custom tools

          • JsonValue; type "namespace"constant

            The type of the tool. Always namespace.

            • NAMESPACE("namespace")

        • class ToolSearchTool:

          Hosted or BYOT tool search configuration for deferred tools.

          • JsonValue; type "tool_search"constant

            The type of the tool. Always tool_search.

            • TOOL_SEARCH("tool_search")

          • Optional<String> description

            Description shown to the model for a client-executed tool search tool.

          • Optional<Execution> execution

            Whether tool search is executed by the server or by the client.

            • SERVER("server")

            • CLIENT("client")

          • Optional<JsonValue> parameters

            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 type

            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")

            • WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")

          • Optional<List<SearchContentType>> searchContentTypes

            • TEXT("text")

            • IMAGE("image")

          • Optional<SearchContextSize> searchContextSize

            High 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("low")

            • MEDIUM("medium")

            • HIGH("high")

          • Optional<UserLocation> userLocation

            The user's location.

            • JsonValue; type "approximate"constant

              The type of location approximation. Always approximate.

              • APPROXIMATE("approximate")

            • Optional<String> city

              Free text input for the city of the user, e.g. San Francisco.

            • Optional<String> country

              The two-letter ISO country code of the user, e.g. US.

            • Optional<String> region

              Free text input for the region of the user, e.g. California.

            • Optional<String> timezone

              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.

          • JsonValue; type "apply_patch"constant

            The type of the tool. Always apply_patch.

            • APPLY_PATCH("apply_patch")

      • JsonValue; type "tool_search_output"constant

        The item type. Always tool_search_output.

        • TOOL_SEARCH_OUTPUT("tool_search_output")

      • Optional<String> id

        The unique ID of this tool search output.

      • Optional<String> callId

        The unique ID of the tool search call generated by the model.

      • Optional<Execution> execution

        Whether tool search was executed by the server or by the client.

        • SERVER("server")

        • CLIENT("client")

      • Optional<Status> status

        The status of the tool search output.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("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.

      • String id

        The unique identifier of the reasoning content.

      • List<Summary> summary

        Reasoning summary content.

        • String text

          A summary of the reasoning output from the model so far.

        • JsonValue; type "summary_text"constant

          The type of the object. Always summary_text.

          • SUMMARY_TEXT("summary_text")

      • JsonValue; type "reasoning"constant

        The type of the object. Always reasoning.

        • REASONING("reasoning")

      • Optional<List<Content>> content

        Reasoning text content.

        • String text

          The reasoning text from the model.

        • JsonValue; type "reasoning_text"constant

          The type of the reasoning text. Always reasoning_text.

          • REASONING_TEXT("reasoning_text")

      • Optional<String> encryptedContent

        The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter.

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • class ResponseCompactionItemParam:

      A compaction item generated by the v1/responses/compact API.

      • String encryptedContent

        The encrypted content of the compaction summary.

      • JsonValue; type "compaction"constant

        The type of the item. Always compaction.

        • COMPACTION("compaction")

      • Optional<String> id

        The ID of the compaction item.

    • ImageGenerationCall

      • String id

        The unique ID of the image generation call.

      • Optional<String> result

        The generated image encoded in base64.

      • Status status

        The status of the image generation call.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • GENERATING("generating")

        • FAILED("failed")

      • JsonValue; type "image_generation_call"constant

        The type of the image generation call. Always image_generation_call.

        • IMAGE_GENERATION_CALL("image_generation_call")

    • class ResponseCodeInterpreterToolCall:

      A tool call to run code.

      • String id

        The unique ID of the code interpreter tool call.

      • Optional<String> code

        The code to run, or null if not available.

      • String containerId

        The ID of the container used to run the code.

      • Optional<List<Output>> outputs

        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.

          • String logs

            The logs output from the code interpreter.

          • JsonValue; type "logs"constant

            The type of the output. Always logs.

            • LOGS("logs")

        • class Image:

          The image output from the code interpreter.

          • JsonValue; type "image"constant

            The type of the output. Always image.

            • IMAGE("image")

          • String url

            The URL of the image output from the code interpreter.

      • Status status

        The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

        • INTERPRETING("interpreting")

        • FAILED("failed")

      • JsonValue; type "code_interpreter_call"constant

        The type of the code interpreter tool call. Always code_interpreter_call.

        • CODE_INTERPRETER_CALL("code_interpreter_call")

    • LocalShellCall

      • String id

        The unique ID of the local shell call.

      • Action action

        Execute a shell command on the server.

        • List<String> command

          The command to run.

        • Env env

          Environment variables to set for the command.

        • JsonValue; type "exec"constant

          The type of the local shell action. Always exec.

          • EXEC("exec")

        • Optional<Long> timeoutMs

          Optional timeout in milliseconds for the command.

        • Optional<String> user

          Optional user to run the command as.

        • Optional<String> workingDirectory

          Optional working directory to run the command in.

      • String callId

        The unique ID of the local shell tool call generated by the model.

      • Status status

        The status of the local shell call.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

      • JsonValue; type "local_shell_call"constant

        The type of the local shell call. Always local_shell_call.

        • LOCAL_SHELL_CALL("local_shell_call")

    • LocalShellCallOutput

      • String id

        The unique ID of the local shell tool call generated by the model.

      • String output

        A JSON string of the output of the local shell tool call.

      • JsonValue; type "local_shell_call_output"constant

        The type of the local shell tool call output. Always local_shell_call_output.

        • LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")

      • Optional<Status> status

        The status of the item. One of in_progress, completed, or incomplete.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ShellCall

      • Action action

        The shell commands and limits that describe how to run the tool call.

        • List<String> commands

          Ordered shell commands for the execution environment to run.

        • Optional<Long> maxOutputLength

          Maximum number of UTF-8 characters to capture from combined stdout and stderr output.

        • Optional<Long> timeoutMs

          Maximum wall-clock time in milliseconds to allow the shell commands to run.

      • String callId

        The unique ID of the shell tool call generated by the model.

      • JsonValue; type "shell_call"constant

        The type of the item. Always shell_call.

        • SHELL_CALL("shell_call")

      • Optional<String> id

        The unique ID of the shell tool call. Populated when this item is returned via API.

      • Optional<Environment> environment

        The environment to execute the shell commands in.

        • class LocalEnvironment:

        • class ContainerReference:

      • Optional<Status> status

        The status of the shell call. One of in_progress, completed, or incomplete.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ShellCallOutput

      • String callId

        The unique ID of the shell tool call generated by the model.

      • List<ResponseFunctionShellCallOutputContent> output

        Captured chunks of stdout and stderr output, along with their associated outcomes.

        • Outcome outcome

          The exit or timeout outcome associated with this shell call.

          • JsonValue;

            • JsonValue; type "timeout"constant

              The outcome type. Always timeout.

              • TIMEOUT("timeout")

          • class Exit:

            Indicates that the shell commands finished and returned an exit code.

            • long exitCode

              The exit code returned by the shell process.

            • JsonValue; type "exit"constant

              The outcome type. Always exit.

              • EXIT("exit")

        • String stderr

          Captured stderr output for the shell call.

        • String stdout

          Captured stdout output for the shell call.

      • JsonValue; type "shell_call_output"constant

        The type of the item. Always shell_call_output.

        • SHELL_CALL_OUTPUT("shell_call_output")

      • Optional<String> id

        The unique ID of the shell tool call output. Populated when this item is returned via API.

      • Optional<Long> maxOutputLength

        The maximum number of UTF-8 characters captured for this shell call's combined output.

      • Optional<Status> status

        The status of the shell call output.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

    • ApplyPatchCall

      • String callId

        The unique ID of the apply patch tool call generated by the model.

      • Operation operation

        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.

          • String diff

            Unified diff content to apply when creating the file.

          • String path

            Path of the file to create relative to the workspace root.

          • JsonValue; type "create_file"constant

            The operation type. Always create_file.

            • CREATE_FILE("create_file")

        • class DeleteFile:

          Instruction for deleting an existing file via the apply_patch tool.

          • String path

            Path of the file to delete relative to the workspace root.

          • JsonValue; type "delete_file"constant

            The operation type. Always delete_file.

            • DELETE_FILE("delete_file")

        • class UpdateFile:

          Instruction for updating an existing file via the apply_patch tool.

          • String diff

            Unified diff content to apply to the existing file.

          • String path

            Path of the file to update relative to the workspace root.

          • JsonValue; type "update_file"constant

            The operation type. Always update_file.

            • UPDATE_FILE("update_file")

      • Status status

        The status of the apply patch tool call. One of in_progress or completed.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

      • JsonValue; type "apply_patch_call"constant

        The type of the item. Always apply_patch_call.

        • APPLY_PATCH_CALL("apply_patch_call")

      • Optional<String> id

        The unique ID of the apply patch tool call. Populated when this item is returned via API.

    • ApplyPatchCallOutput

      • String callId

        The unique ID of the apply patch tool call generated by the model.

      • Status status

        The status of the apply patch tool call output. One of completed or failed.

        • COMPLETED("completed")

        • FAILED("failed")

      • JsonValue; type "apply_patch_call_output"constant

        The type of the item. Always apply_patch_call_output.

        • APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")

      • Optional<String> id

        The unique ID of the apply patch tool call output. Populated when this item is returned via API.

      • Optional<String> output

        Optional human-readable log text from the apply patch tool (e.g., patch results or errors).

    • McpListTools

      • String id

        The unique ID of the list.

      • String serverLabel

        The label of the MCP server.

      • List<Tool> tools

        The tools available on the server.

        • JsonValue inputSchema

          The JSON schema describing the tool's input.

        • String name

          The name of the tool.

        • Optional<JsonValue> annotations

          Additional annotations about the tool.

        • Optional<String> description

          The description of the tool.

      • JsonValue; type "mcp_list_tools"constant

        The type of the item. Always mcp_list_tools.

        • MCP_LIST_TOOLS("mcp_list_tools")

      • Optional<String> error

        Error message if the server could not list tools.

    • McpApprovalRequest

      • String id

        The unique ID of the approval request.

      • String arguments

        A JSON string of arguments for the tool.

      • String name

        The name of the tool to run.

      • String serverLabel

        The label of the MCP server making the request.

      • JsonValue; type "mcp_approval_request"constant

        The type of the item. Always mcp_approval_request.

        • MCP_APPROVAL_REQUEST("mcp_approval_request")

    • McpApprovalResponse

      • String approvalRequestId

        The ID of the approval request being answered.

      • boolean approve

        Whether the request was approved.

      • JsonValue; type "mcp_approval_response"constant

        The type of the item. Always mcp_approval_response.

        • MCP_APPROVAL_RESPONSE("mcp_approval_response")

      • Optional<String> id

        The unique ID of the approval response

      • Optional<String> reason

        Optional reason for the decision.

    • McpCall

      • String id

        The unique ID of the tool call.

      • String arguments

        A JSON string of the arguments passed to the tool.

      • String name

        The name of the tool that was run.

      • String serverLabel

        The label of the MCP server running the tool.

      • JsonValue; type "mcp_call"constant

        The type of the item. Always mcp_call.

        • MCP_CALL("mcp_call")

      • Optional<String> approvalRequestId

        Unique identifier for the MCP tool call approval request. Include this value in a subsequent mcp_approval_response input to approve or reject the corresponding tool call.

      • Optional<String> error

        The error from the tool call, if any.

      • Optional<String> output

        The output from the tool call.

      • Optional<Status> status

        The status of the tool call. One of in_progress, completed, incomplete, calling, or failed.

        • IN_PROGRESS("in_progress")

        • COMPLETED("completed")

        • INCOMPLETE("incomplete")

        • CALLING("calling")

        • FAILED("failed")

    • class ResponseCustomToolCallOutput:

      The output of a custom tool call from your code, being sent back to the model.

      • String callId

        The call ID, used to map this custom tool call output to a custom tool call.

      • Output output

        The output from the custom tool call generated by your code. Can be a string or an list of output content.

        • String

        • List<FunctionAndCustomToolCallOutput>

          • 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.

      • JsonValue; type "custom_tool_call_output"constant

        The type of the custom tool call output. Always custom_tool_call_output.

        • CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")

      • Optional<String> id

        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.

      • String callId

        An identifier used to map this custom tool call to a tool call output.

      • String input

        The input for the custom tool call generated by the model.

      • String name

        The name of the custom tool being called.

      • JsonValue; type "custom_tool_call"constant

        The type of the custom tool call. Always custom_tool_call.

        • CUSTOM_TOOL_CALL("custom_tool_call")

      • Optional<String> id

        The unique ID of the custom tool call in the OpenAI platform.

      • Optional<String> namespace

        The namespace of the custom tool being called.

    • ItemReference

      • String id

        The ID of the item to reference.

      • Optional<Type> type

        The type of item to reference. Always item_reference.

        • ITEM_REFERENCE("item_reference")